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

Question

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

我知道可以使用.. blah blah blah在.rst文件中包含注释，但是有没有什么方法可以包含只被Sphinx视为注释的行呢？(或者，让Sphinx忽略该行。)

Answer 1

您希望在GitHub中包含.rst文件中的一行，但在您的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，并且应打印注释。若要在conf.py中隐藏注释集show_github_hote = False，请执行以下操作。