Question

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

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

Answer 1

也许我的答案有点迟了，但我设法通过exclude patterns in the config file与Sphinx合作。

我的文档部分针对用户，部分针对管理员有些页面的文件名包含单词admin，和你一样，我想构建两个版本：一个包含所有内容（管理员文档），另一个包含所有＆＃34; admin＆＃34;排除的页面（用户文档）。

排除所有＆＃34; admin＆＃34;在所有子文件夹中的页面，您必须将此行添加到配置文件conf.py：

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

这很容易。

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

我自己找不到解决方案，所以我asked a question here on SO得到了an answer：

配置文件只是一个Python文件，可以包含Python代码，它将在构建时执行。
您可以通过命令行传递参数（＆＃34; tags＆＃34;），可以在配置文件中查询。

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

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

现在我可以在不传递任何内容的情况下运行构建，这将排除＆＃34; admin＆＃34;文件：

make clean
make html

⇒这是我的用户文档

...我可以设置＆＃34; adminmode＆＃34;标签，不排除任何内容：
（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.

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文件，如果需要，您可以智能和自动地使您的包含标准。

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

3 个答案: