使用 Sphinx 从单一来源生成内部和外部文档

Question

我正在尝试查找有关 Sphinx 将文档的某些位标记为 'internal' 并将其构建为 sphinx-build -b -include internal source output 的能力的信息，其中 -include 标志将包含一系列标记包含在输出中。

这将允许我生成 2 个版本（或更多）我的文档，同时保持其单一来源。

示例：

.. audience::internal

Page title
============

This whole page will be available only in the internal docs.

或

Page title
============

This whole page will be available in the internal and external docs. 

.. audience::internal

That p will only be available in the internal docs.

This p will be available in the internal and external docs.

有这样的机制吗？如果没有，会不会很难制作？

Answer 1

Sphinx 扩展 ifconfig 可能会满足您的要求，尽管您必须缩进内容。

Answer 2

ifconfig确实是一种方法，但经过询问，似乎有更好的机制：

.. only:: directive

用它来标记某些东西：

.. only:: internal

   Page title
   ============

   This whole page will be available only in the internal docs.

然后你可以运行一个带有-t选项的构建来发布所有标记为internal（或你使用的任何东西）

sphinx-build -t internal -b html source output

使用 Sphinx 从单一来源生成内部和外部文档

Generate internal and external docs from single source using Sphinx

python-sphinx

conditional-compilation