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

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

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

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

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

在狮身人面像中是否有内置的方式来做类似的事情？如果有人在做类似的事情，您能告诉我们一下并给我们一些您工作流程上的亮点吗？

解决方案

过去，我想编译两个文档，一个是公共文档，另一个是私有文档，但是我不想拆分我的源文件（rst）。

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

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

从而

a_doc_for_basic.rst

.. meta::
    :scope: basic

Title
=====

My content

a_doc_for_code.rst

.. meta::
    :scope: code

Title
=====

My content

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

a_doc_for_all.rst

Title
=====

My content

.. only:: code

    a piece of code

您可以在这里找到插件源

如您所见，该插件非常简单，感谢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#meta 的原始用法

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

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

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

否则，您可以toctree对所有对象使用相同的名称，tag因为在为每个标签编译文档时toctree，插件将对其进行编辑以生成树，而无需引用不匹配的文档。

PS：我的插件并不完美，但是我回答了我的需求，您可以启发并更新它。