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

Question

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

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

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

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

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

在Sphinx中有没有内置的方法可以做这样的事情？如果某人正在做类似的事情，您能否告诉我们并告诉我们您工作流程的一些亮点？

Answer 1

过去我想编译两个文档，一个公共文件和一个私有文件，但我不想拆分我的源文件（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

您可以找到插件来源here

正如您所看到的，该插件非常简单，并且可以使用regexp。这意味着（regexp）存在限制：

• 指令.. meta:: :scope:必须位于文件顶部（之前没有行）
• 指令.. meta:: :scope:必须与正则表达式^\.\. 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，因为在为每个标记编译doc时，插件会编辑toctree以生成树而不参考没有匹配的文档。

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