sphinx文档_使用Sphinx构建自定义文档工作流

sphinx文档

Sphinx是用于创建文档的流行应用程序，类似于JavaDoc或Jekyll。但是，与其他工具相比，Sphinx的重组文本输入允许更高程度的自定义。

本教程将说明如何自定义Sphinx以适合您的工作流程。您可以继续使用GitHub上的示例代码。

一些定义

Sphinx远远不仅仅使您能够使用预定义标签设置文本样式。它允许您通过定义新的角色和指令来调整和自动化文档。角色是一个单词元素，通常在文档中以内联方式呈现，而指令可以包含更复杂的内容。这些可以包含在一个域中。

Sphinx 域是指令和角色以及其他一些东西（例如索引定义）的集合。您的下一个Sphinx域可能是一种特定的编程语言（Sphinx是为创建Python文档而开发的）。或者，您可能有一个命令行工具可以反复执行相同的命令模式（例如， 工具<command> --args ）。您可以使用自定义域对其进行记录，并在此过程中添加指令和索引。

这是我们食谱域中的一个示例：

The recipe contains `tomato` and `cilantro`.

.. rcp :recipe:: TomatoSoup :contains: tomato cilantro salt pepper

This recipe is a tasty tomato soup , combine all ingredients and cook.

现在我们已经定义了TomatoSoup食谱，我们可以使用自定义角色refef在文档的任何地方引用它。例如：

 You can use the :rcp:reref:`TomatoSoup` recipe to feed your family.

这使我们的食谱可以显示在两个索引中：第一个列出所有食谱，第二个列出按成分列出的所有食谱。

域中有什么？

Sphinx域是一个专门的容器，将角色，指令和索引等联系在一起。该域具有一个名称（ rcp ），用于在文档源中寻址其组件。它在软件包的setup（）方法中向Sphinx宣布其存在。 Sphinx可以从那里找到角色和指令，因为它们是域的一部分。

此域还充当此样本中对象的中央目录。使用初始数据，它定义了两个变量，对象和obj2ingredient 。这些包含所有已定义对象的列表（ 所有配方 ）和将规范成分名称映射到对象列表的哈希。

initial_data = {

        'objects' : [ ] ,  # object list

        'obj2ingredient' : { } ,  # ingredient -> [objects]

        }

在整个扩展中，我们使用对象命名的方式很常见。对于创建的每个对象，规范名称为rcp。<typename>。<objectname> ，其中<typename>是对象的Python类型，而<objectname>是文档编写者提供的对象名称。这使扩展能够使用共享相同名称的不同对象类型。

为我们的对象指定规范的名称和中心位置是一个巨大的优势。我们的索引和交叉引用代码都使用此功能。

`自定义角色和指令`

在我们的示例中， .. rcp：recipe ::表示自定义指令。您可能会认为为这些项目创建自定义语法过于具体，但是它说明了在Sphinx中可以实现的自定义程度。这提供了丰富的标记，可以构造文档并生成更好的文档。专业化使我们能够从文档中提取信息。

我们对该指令的定义将提供最小的格式设置，但它将起作用。

class RecipeNode ( ObjectDescription ) :

        """A custom node that describes a recipe."""

required_arguments = 1

option_spec = { 'contains' : rst. directives . unchanged_required }

对于此指令， required_arguments告诉Sphinx使用一个参数，即配方名称。 option_spec列出了可选参数，包括它们的名称。最后， has_content指定将有更多的重组文本作为此节点的子级。

我们还实现了多种方法：

handle_signature（）实现解析指令的签名，并将对象的名称和类型传递给其超类
add_taget_and_index（）为此节点添加一个目标（链接到）和一个索引条目

`创建索引`

IngredientIndex和RecipeIndex都从Sphinx的Index类派生。它们实现自定义逻辑，以生成定义索引的值的元组。请注意， RecipeIndex是仅具有一个条目的简并索引。扩展它以覆盖更多的对象类型-并从RecipeDomain移到CookbookDomain-尚不是代码的一部分。

两个索引都使用generate（）方法来完成其工作。该方法将来自我们域的信息进行组合，排序，然后以Sphinx接受的列表结构返回。有关更多信息，请参见Sphinx Domain API页面。

第一次访问Domain API页面时，您可能会对结构感到有些不知所措。但是我们的成分索引只是一个元组列表，例如（'tomato'，'TomatoSoup'，'test'，'rec-TomatoSoup'...）。

`参考配方`

添加交叉引用并不困难（但这也不是给定的）。将XRefRole添加到域中并实现方法resolve_xref（）。通过使用自定义角色来引用类型，即使两个对象具有相同的名称，我们也可以明确地引用任何对象。如果您在Domain中查看resolve_xref（）的参数，则会看到typ和target 。这些定义了交叉引用类型及其目标名称。我们将使用target来从域的对象中解析目标，因为我们目前只有一种类型的节点。

我们可以通过以下方式将交叉引用角色添加到RecipeDomain ：

roles = {

        'reref' : XRefRole ( )

        }

我们没有什么可以实现的。您只需要做的就是定义一个有效的resolve_xref（）并将XRefRole附加到域。

`进一步阅读`

如果您想了解更多信息，请查看以下资源：

reStructured Text Primer：什么是角色和指令？
Sphinx扩展开发人员指南
GitHub上的示例代码存储库

翻译自: https://opensource.com/article/18/11/building-custom-workflows-sphinx

sphinx文档