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

Question

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

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

Answer 1

也许我的回答来的有点晚，但我设法通过 exclude patterns in the config file 用 Sphinx 做到了这一点.

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

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

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

这是最简单的部分。

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

我自己没有找到解决办法，所以我asked a question here on SO并得到 an answer :

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

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

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

现在我可以在不传递任何内容的情况下运行构建，这将排除“管理员”文件:

make clean
make html

⇒ 这是我的用户文档

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

set SPHINXOPTS=-t adminmode
make clean
make html

⇒ 这是我的管理文档。

---

奖励:

我可以使用相同的标签来忽略页面上的某些特定内容，Including content based on tags .

例子:

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.