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

Question

我在GitHub上有一個README.rst，該文件也已合並到Sphinx生成的Python項目文檔中。 我想在文件頂部添加一個注釋，該注釋將顯示在GitHub（僅呈現.rst）上，但未顯示在Sphinx生成的文檔中。

我知道我可以使用.. blah blah blah在.rst文件中添加注釋，但是有什么方法可以包含僅被Sphinx視為注釋的行？ （或者讓Sphinx忽略該行。）

Answer 1

您希望在.rst文件中的一行包含在GitHub上，但在Sphinx文檔中被忽略。

可以使用inconfig指令sphinx.ext.ifconfig來實現–通過這種方式包含基於配置的內容 。

在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 。