Python-sphinx：忽略.rst文件中的文本

Question

我在GitHub上有一个README.rst，它也被整合到Sphinx生成的Python项目文档中。我想在文件的顶部添加一个注释，该注释将显示在GitHub上（它只是呈现.rst）但未在Sphinx生成的文档中显示。

我知道我可以使用.rst在.. blah blah blah文件中添加评论，但是有哪些方法可以包含仅被Sphinx评为评论的行？ （或者，让Sphinx忽略该行。）

Answer 1

您想要在.rst文件中的一行包含在GitHub上，但在Sphinx文档中被忽略。

可以使用inconfig指令sphinx.ext.ifconfig – Include content based on configuration这样实现。

在您的conf.py文件中，检查是否已启用sphinx.ext.ifconfig扩展名

# conf.py
extensions = [
    ...
    'sphinx.ext.ifconfig',
    ...
]

并注册一个变量

# conf.py
# custom variables
def setup(app):
    app.add_config_value(name='show_github_hote', default=True, rebuild='env')

# uncomment in Sphinx doc to hide the note
# show_github_hote = False

然后在您的.rst文件中

.. ifconfig:: show_github_hote

    THIS NOTE IS FOR GITHUB ONLY.

    Use bigger indentation for the note.

Further text with smaller indent. 

如果未设置show_github_hote var，则默认值为True，并且应打印注释。隐藏show_github_hote = False中的conf.py笔记集。