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

【问题标题】：Generate internal and external docs from single source using Sphinx使用 Sphinx 从单一来源生成内部和外部文档
【发布时间】：2017-05-12 16:56:27
【问题描述】：

我正在尝试查找有关 Sphinx 将某些文档位标记为“内部”的能力的信息，并像 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.

有这样的机制吗？如果没有，那会很难创建吗？

【问题讨论】：

标签： python-sphinx conditional-compilation

【解决方案1】：

Sphinx 扩展 ifconfig 可能会做你想做的事，尽管你必须缩进内容。

【讨论】：

【解决方案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

【讨论】：