如何创建Sphinx指令：HTML含指定类、LaTeX不输出内容

方法一：自定义Sphinx指令（推荐，语法简洁） #

这种方式可以实现你想要的单一指令语法，同时完美支持嵌套内容（比如figure、table这类指令）。

1. 编写扩展代码 #

可以直接在项目的conf.py末尾添加以下代码，或者单独创建一个扩展文件（比如hidden_content.py）后在conf.py中加载：

from sphinx.util.docutils import SphinxDirective
from docutils.nodes import Container

class HiddenContainer(Container):
    pass

class HiddenDirective(SphinxDirective):
    has_content = True
    required_arguments = 0
    optional_arguments = 0
    final_argument_whitespace = True
    option_spec = {}

    def run(self):
        # 创建带指定类的容器节点
        container = HiddenContainer('', classes=['hidden-content'])
        # 解析嵌套内容，自动处理内部的所有指令
        self.state.nested_parse(self.content, self.content_offset, container)
        return [container]

def setup(app):
    # HTML渲染逻辑：输出带class的div容器
    def visit_hidden_html(self, node):
        self.body.append(self.starttag(node, 'div', CLASS='hidden-content'))

    def depart_hidden_html(self, node):
        self.body.append('</div>\n')

    # LaTeX渲染逻辑：直接跳过整个节点，不输出任何内容
    def visit_hidden_latex(self, node):
        self.skip_node()

    def depart_hidden_latex(self, node):
        pass

    # 注册节点和指令
    app.add_node(HiddenContainer,
                html=(visit_hidden_html, depart_hidden_html),
                latex=(visit_hidden_latex, depart_hidden_latex))
    app.add_directive('hidden', HiddenDirective)

    return {
        'version': '0.1',
        'parallel_read_safe': True,
    }

2. 配置与使用 #

• 若代码写在conf.py里，直接保存即可；若用单独扩展文件，在conf.py中添加extensions = ['hidden_content']（确保文件在Python路径中）。
• 使用方式完全符合你的示例：

  .. hidden ::
  
     This content should not be visible in LaTeX and should have a specific class in HTML. 
  
     .. figure :: images/hidden.png
        
        This image should be hidden in PDF and displayed differently in HTML. 
  
     .. table :: This table should be hidden in PDF as well.
  
     +------------------------+------------+----------+----------+
     | Header row, column 1   | Header 2   | Header 3 | Header 4 |
     | (header rows optional) |            |          |          |
     +========================+============+==========+==========+
     | body row 1, column 1   | column 2   | column 3 | column 4 |
     +------------------------+------------+----------+----------+
     | body row 2             | ...        | ...      |          |
     +------------------------+------------+----------+----------+
  

3. 添加HTML样式提示 #

给内部人员标记隐藏内容，在项目的_static/custom.css中添加样式（需在conf.py配置html_css_files = ['custom.css']）：

.hidden-content {
    border-left: 4px solid #ffc107;
    background-color: #fff3cd;
    padding: 1rem;
    margin: 1rem 0;
}

.hidden-content::before {
    content: "⚠️ 内部隐藏内容：对外分享时需隐藏";
    display: block;
    font-weight: bold;
    margin-bottom: 0.5rem;
    color: #856404;
}

方法二：使用Sphinx内置指令组合（无需写扩展） #

不想自定义扩展的话，直接用only和container指令组合，效果完全一致：

.. only:: html

   .. container:: hidden-content

      This content should not be visible in LaTeX and should have a specific class in HTML. 

      .. figure :: images/hidden.png
         
         This image should be hidden in PDF and displayed differently in HTML. 

      .. table :: This table should be hidden in PDF as well.

      +------------------------+------------+----------+----------+
      | Header row, column 1   | Header 2   | Header 3 | Header 4 |
      | (header rows optional) |            |          |          |
      +========================+============+==========+==========+
      | body row 1, column 1   | column 2   | column 3 | column 4 |
      +------------------------+------------+----------+----------+
      | body row 2             | ...        | ...      |          |
      +------------------------+------------+----------+----------+

only:: html确保内容仅在HTML构建时输出，container指令给内容添加hidden-content类，同样支持所有嵌套指令。

内容的提问来源于stack exchange，提问作者lennessy