如何在Sphinx文档构建时隐藏单个章节？求对应directive

RST本身并没有原生的.. hidden::指令，但有几种实用方法可以实现你想要的“构建时隐藏单个章节”的需求，下面给你详细说明：

方法1：使用原生only指令（无需额外配置） #

Sphinx和大部分RST解析器都支持.. only::条件编译指令，你可以用never作为条件，让指定内容在任何输出格式中都被忽略：

Visible section
===============
这里是我想要展示的示例内容

.. only:: never

   Not visible section
   ===================
   这是我编写的文本，但当前构建时希望将其从最终文档中隐藏。

把需要隐藏的章节缩进后放在.. only:: never的块里，这样不管是生成HTML、PDF还是其他格式，这个章节都不会出现在最终产物中。

方法2：自定义hidden指令（完全贴合你的设想） #

如果你更偏好.. hidden::这种直观的写法，可以通过Sphinx扩展自定义一个简单的指令，让它不输出任何内容。只需要在你的文档项目的conf.py中添加以下代码：

from docutils.parsers.rst import Directive
from docutils import nodes

class HiddenDirective(Directive):
    has_content = True
    def run(self):
        # 直接返回空列表，不生成任何文档节点
        return []

def setup(app):
    app.add_directive('hidden', HiddenDirective)

之后你就可以完全按照你设想的方式使用了：

Visible section
===============
这里是我想要展示的示例内容

.. hidden::

   Not visible section
   ===================
   这是我编写的文本，但当前构建时希望将其从最终文档中隐藏。

额外提示：如果要隐藏整个文件 #

如果你的需求是隐藏整个RST文件，而不是单个章节，可以在conf.py中修改exclude_patterns配置，把目标文件路径加进去：

exclude_patterns = ['path/to/your/hidden_file.rst']

不过这个方法只适用于整文件隐藏，不适合单个章节的场景。

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