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

【问题标题】：Python-sphinx: ignore text in .rst filePython-sphinx：忽略 .rst 文件中的文本
【发布时间】：2016-03-07 15:54:45
【问题描述】：

我在 GitHub 上有一个 README.rst，它也包含在 Sphinx 生成的 Python 项目文档中。我想在文件顶部包含一个注释，该注释将显示在 GitHub 上（它只是呈现 .rst），但不会显示在 Sphinx 生成的文档中。

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

【问题讨论】：

狮身人面像的标签错误，你应该把“python-sphinx”
谢谢！进行了更改。
鉴于 Sphinx 和 GitHub 都将其解释为 RST，我不明白您怎么能在其中一个中包含评论，而在另一个中没有。
好吧，你可以拥有像 .. note:: 这样的东西，它们在 Sphinx 中做一些事情，但在普通 RST 中做的不多。而且我想它不需要是评论，我只是希望 Sphinx 不在最终生成的文档中包含文本。

标签： python github python-sphinx

【解决方案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。

【讨论】：