在 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 文档，“根据输出格式化程序，注释可能会从处理后的输出中删除。” 但是，我在HTML 输出配置文档中没有看到任何选项。

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

提前致谢！

Answer 1

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

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.

编辑

注释是块，而不是内联。没有内联注释语法。然而你可能会滥用替代品。

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

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

您还可以使用一种技巧，即通过包含要评论的文本的块来指定CSS 类rst-class.comment>strong，然后在评论周围使用内联标记，并应用具有 CSS 选择器的自定义样式，这样可以从视觉显示中隐藏评论在 HTML 中。

#reST

.. rst-class:: comment

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

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