在 Sphinx HTML 输出中排除 reStructuredText 注释

Question

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

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

我正在使用 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.

编辑

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

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

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

您还可以使用一种技巧，将 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;}