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

Question

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

我可以编写一个构建脚本来移动文件来实现这一点,但如果有一种方法可以告诉sphinx在特定构建期间排除或包含特定文档,那将会非常好.

Answer 1

也许我的答案有点晚了,但我设法通过配置文件中的排除模式与Sphinx做到这一点.

我的文档部分针对用户,部分针对管理员.
有些页面的文件名包含单词admin,和你一样,我想构建两个版本:一个包含所有内容(管理员文档),另一个包含所有"admin"页面(用户文档).

要排除所有子文件夹中的所有"admin"页面,您必须将此行添加到配置文件中conf.py:

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

这很容易.

我的问题是我不知道如何运行构建两次,一个有一个没有排除模式而没有使用两个不同的配置文件.

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

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

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

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

该only和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 文件，您可以根据需要使您的包含标准变得智能和自动。