RestructuredText文件能否设置私有段落？如何阻止Sphinx渲染？

当然支持！我自己在迁移文档到ReadTheDocs的时候也遇到过完全一样的需求，下面给你几种经过实践验证的靠谱方法：

方法1：原生注释块（适合零散内容） #

RST本身就支持注释语法，用.. （两个点加空格）开头的行，Sphinx会直接忽略，不会渲染到HTML里：

.. 这是内部专属的私有备注，只会在源文件里可见
.. 多行注释的话，每一行都要以.. 开头才行

注意：这种方式简单直接，但如果是大段内部内容，每一行都加前缀会有点繁琐。

方法2：only指令结合构建标签（推荐，适合大段内容） #

如果需要更灵活的控制——比如内部构建时显示内容，对外（ReadTheDocs）构建时隐藏——可以用Sphinx的only指令，配合自定义构建标签：

1. 不需要修改Sphinx的conf.py，只需要在内部构建文档时，用sphinx-build -t internal命令（internal是你自定义的标签名，随便取）
2. 在RST文件里这样标记私有内容：

.. only:: internal

   这是大段的内部专属内容，只有当构建时指定了`internal`标签才会被渲染
   这里可以直接写多行文本，不需要每行加前缀，非常方便
   甚至可以嵌套其他RST语法，比如列表、代码块都没问题

关键提示：ReadTheDocs的自动构建默认不会添加任何自定义标签，所以对外发布的HTML里这段内容会被完全跳过，完美匹配你的需求。

方法3：hidden扩展指令（可选） #

如果你已经在用Sphinx的某些扩展，还可以用hidden指令，但这个需要额外依赖，而且前两种方法已经足够覆盖大部分场景，没必要多增加复杂度。

我个人最推荐方法2，因为它兼顾了对外隐藏和内部可查看的灵活性，操作起来也不麻烦。如果只是几个零散的内部备注，方法1就足够省事了。

内容的提问来源于stack exchange，提问作者Robert_LY