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

Question

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

[我知道我可以使用.rst将注释添加到.. blah blah blah文件中，但是有什么方法可以包含仅被Sphinx视为注释的行？ （或者让Sphinx忽略该行。）

Answer 1

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

可以使用ifconfig指令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。