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

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

提前致谢！

Answer 1

你的语法有点不对劲。 空格在 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.

编辑

注释是块，不是内联的。 没有内联注释语法。 但是，您可以滥用替换。

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

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

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

#reST

.. rst-class:: comment

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

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