在Sphinx中有条件地编译文档部分

Question

我们正计划为我们的软件项目创建一个用户手册。目前，与代码相关的所有内容都记录在Sphinx中，我们希望在手册中使用Sphinx。在

由于我们正在编写科学/工程软件，因此会有许多主题，如应力、应变、数值算法等。对于每个主题，我们将有几个阶段的信息：

1. 基本信息：这个一两句话的描述可以用在任何我们需要对主题进行简短总结的地方。示例：机械应力的简单定义。在
2. 更详细的描述：这个一段式的解释可以用作帮助页面的开头，或者更详细的主题列表中的摘要。例如，一段关于机械应力的段落介绍了轴向应力的方程式。在
3. 技术信息。这可以是关于如何将主题应用于我们的软件用户遇到的问题的多个段落。在
4. 代码信息。这将是与在代码中遇到主题的位置相关的文档。例如，我们可以指出我们实现的某个数值算法。我们可以像现在一样使用sphinx apidoc。在

如您所见，信息逐渐变得更加复杂。我们希望在各自的.rst文件中管理每个主题，并根据需要获取所需的信息。例如，我们可能想在工具提示中使用基本信息部分。在实际的帮助菜单中，我们可以使用某类主题的目录中的详细描述。在关于这个主题的整篇文章中，我们可以提供技术信息以及基本的和更详细的描述，就像在一个完整的pdf手册中一样。最后，我们希望只在内部文档中保留代码信息。在

最好将单个主题的所有信息保存在一个文件中，但是根据我们生成的文档有条件地编译不同的部分。在

在斯芬克斯有没有一种内在的方式来做这样的事情？如果有人在做类似的事情，你能告诉我们一些关于你的工作流程的重点吗？在

Answer 1

过去我想编译两个文档，一个public和一个private，但我不想分割我的源文件（rst）。在

第一步我找到了only指令，我认为这是解决方案。但是当我想要一个完整的rst文件在公共或私有文档中时，我不能不缩进整个文件。在

所以我写了我自己的Sphinx插件（scope）来管理我所有的案例。为了成功，我使用了可以放在文件顶部的meta指令。在

因此

医生_基本.rst

.. meta::
    :scope: basic

Title
=====

My content

医生_代码.rst

^{pr2}$

您可以继续对文件使用.. only::指令

医生_全部.rst

Title
=====

My content

.. only:: code

    a piece of code

您可以找到插件源here

正如你所看到的，这个插件非常简单，多亏了regexp。这意味着（regexp）存在限制：

• 指令.. meta:: :scope:必须放在文件的顶部（前面没有行）
• 指令.. meta:: :scope:必须与regexp ^\.\. meta::\s+:scope: ([a-zA-Z0-9_-]+)匹配
• 指令.. meta:: :scope:可以管理多个标记，但您可以根据需要轻松地更新插件
• 插件偏离了meta指令的原始用法docutils.sourceforge.net/docs/ref/rst/directives.html元数据

之后，您可以使用以下命令构建您的文档

sphinx-build ... -t <tag> ...

sphinx-build ... -t code ...

另一方面，您可以对所有的toctree使用相同的toctree，因为在编译每个标记的doc时，toctree将被插件编辑以生成一个树，而不引用不匹配的文档。在

注：我的插件不完美，但我回应了我的需要，你可以启发和更新它。在