如何配置 Sphinx 有条件地排除某些页面？

Question

使用 Sphinx 生成文档时，我希望能够生成文档的两个版本：一个包含所有内容，另一个仅包含一组特定的页面。实现这一目标的最佳方法是什么？

我可以编写一个构建脚本来移动文件来实现此目的，但如果有一种方法告诉 sphinx 在特定构建期间排除或包含特定文档，那就太好了。

Answer 1

也许我的答案来得有点晚了，但我设法通过 排除中的模式来使用 Sphinx 来做到这一点配置文件。

我的文档部分供用户使用，部分供管理员使用。
有些页面的文件名包含单词 admin ，和你一样，我想构建两个版本：一个包含所有内容（管理文档），另一个包含所有“管理”页面（用户文档） ）。

要排除所有子文件夹中的所有“管理”页面，您必须将此行添加到配置文件 conf.py 中：

exclude_patterns = ['**/*admin*']

这是简单的部分。

我的问题是，我不知道如何在不使用两个不同的配置文件的情况下运行构建两次，一次使用排除模式，一次不使用排除模式。

我自己没有找到解决方案，所以我在这里问了一个问题并得到了答案：

• 配置文件只是一个Python文件，可以包含Python代码，它将在构建时执行。
• 您可以通过命令行传递参数（“标签”）可以在配置文件中查询。

所以我的配置文件中有这个排除模式：

exclude_patterns = ['**/*admin*']
if tags.has('adminmode'):
    exclude_patterns = []

现在我可以运行构建而不传递任何内容，这将排除“admin”文件：

make clean
make html

⇒这是我的用户文档

......我可以设置“adminmode”标签，它不会排除任何东西：
（Windows 命令行语法）

set SPHINXOPTS=-t adminmode
make clean
make html

⇒ 这是我的管理文档。

---

奖励：

我可以使用相同的标签来忽略页面上的某些特定内容，通过包含基于标签的内容。

例子：

regular documentation
=====================

This paragraph and its headline will always be visible.

.. only:: adminmode

        secret admin stuff
        ------------------

        This paragraph will be visible in the admin docs only.


This will (again) always be visible.

Answer 2

仅< /a> 和 ifconfig 指令可用于在页面内应用条件。

似乎没有任何简单的方法可以使用条件来完全排除整个页面（.rst 文件）。

以下内容（在index.rst中）在生成HTML输出时排除了对index.html中toctree中doc2.html的引用：

.. toctree::
   doc1.rst

.. only:: latex

   .. toctree::
      doc2.rst

但这实际上不起作用。 doc2.html 文件仍然会生成，并且当 doc1.html 是当前主题时，可以通过“下一个主题”链接访问该文件。

Answer 3

sphinx.ext.ifconfig 怎么样？您可以在 conf.py 文件中设置配置值。由于这是一个常规的 Python 文件，因此如果需要，您可以使包含标准变得智能且自动。