在 Sphinx HTML 输出中排除 reStructuredText 注释

Question

我想在 reStructuredText 文档中添加一些注释，这些注释在我构建文档时不会显示。例如，我想将以下内容放入文件中：

This is the source of my .rst file. I would like the following block to be excluded when the docs are built.
..
    This should not show up in the HTML.
    This should not either.

This text would show up in the HTML, as we're past the comment block.

根据 Sphinx docs, "Depending on the output formatter, comments may be removed from the processed output." However, I don't see any options for that in the HTML output configuration docs.

我正在使用 Sphinx (sphinx-build) 构建我的文档。我使用 sphinx-quickstart 进行设置，因此通过 make html.

进行构建

提前致谢！

Answer 1

你的语法有点不对劲。白色 space 在 reST 中有意义。您必须用空行分隔块，如下所示：

This is the source of my .rst file. I would like the following block to be excluded when the docs are built.

..  This should not show up in the HTML.
    This should not either.

This text would show up in the HTML, as we're past the comment block.

编辑

评论是块状的，不是内联的。没有内联注释语法。但是你可以滥用 substitutions.

.. |This is my comment that will be replaced by nothing| replace:: \

Hello |This is my comment that will be replaced by nothing| World!

您还可以使用 hack 指定 CSS class via rst-class 到包含您要评论的文本的块，然后在评论周围使用内联标记，并应用具有 CSS 类似 .comment>strong 的选择器，它在 HTML.

中隐藏了视觉显示中的评论

#reST

.. rst-class:: comment

Block of text that **MY COMMENT** contains a comment.

#CSS
p.comment>strong {display:none;}

在 Sphinx HTML 输出中排除 reStructuredText 注释

Exclude reStructuredText comments in Sphinx HTML output

python

restructuredtext

python-3.x

python-sphinx