扩展构建过程¶

本教程的目的是创建一个比在使用角色和指令扩展语法中创建的更全面的扩展。虽然该指南只涵盖了编写自定义的角色和指令，但本指南涵盖了对 Sphinx 构建过程的更复杂扩展；添加多个指令以及自定义节点、附加配置值和自定义事件处理程序。

为此，我们将介绍一个 todo 扩展，它添加了在文档中包含待办事项条目并将其集中收集的功能。这类似于与 Sphinx 一起分发的 sphinx.ext.todo 扩展。

概述¶

注意

要了解此扩展的设计，请参阅重要对象和构建阶段.

我们希望扩展为 Sphinx 添加以下内容

一个 todo 指令，其中包含一些标记为“TODO”的内容，只有在设置新的配置值时才会在输出中显示。默认情况下，待办事项条目不应出现在输出中。
一个 todolist 指令，它创建整个文档中所有待办事项条目的列表。

为此，我们需要向 Sphinx 添加以下元素

新的指令，名为 todo 和 todolist。
新的文档树节点来表示这些指令，通常也称为 todo 和 todolist。如果新指令仅生成一些由现有节点表示的内容，则我们不需要新节点。
一个新的配置值 todo_include_todos（配置值名称应以扩展名称开头，以保持唯一性），它控制待办事项条目是否包含在输出中。
新的事件处理程序：一个用于 doctree-resolved 事件，用于替换 todo 和 todolist 节点，一个用于 env-merge-info 用于合并来自并行构建的中间结果，以及一个用于 env-purge-doc（稍后将说明原因）。

先决条件¶

与使用角色和指令扩展语法一样，我们不会通过 PyPI 分发此插件，因此我们再次需要一个 Sphinx 项目来调用它。您可以使用现有的项目或使用 sphinx-quickstart 创建一个新的项目。

我们假设您使用的是单独的源 (source) 和构建 (build) 文件夹。您的扩展文件可以位于项目中的任何文件夹中。在本例中，我们执行以下操作

在 source 中创建一个 _ext 文件夹
在 _ext 文件夹中创建一个名为 todo.py 的新 Python 文件

以下是一个示例，展示了您可能获得的文件夹结构

└── source
    ├── _ext
    │   └── todo.py
    ├── _static
    ├── conf.py
    ├── somefolder
    ├── index.rst
    ├── somefile.rst
    └── someotherfile.rst

编写扩展¶

打开 todo.py 并将以下代码粘贴到其中，我们将在稍后详细解释所有代码

from docutils import nodes
from docutils.parsers.rst import Directive

from sphinx.application import Sphinx
from sphinx.locale import _
from sphinx.util.docutils import SphinxDirective
from sphinx.util.typing import ExtensionMetadata


class todo(nodes.Admonition, nodes.Element):
    pass


class todolist(nodes.General, nodes.Element):
    pass


def visit_todo_node(self, node):
    self.visit_admonition(node)


def depart_todo_node(self, node):
    self.depart_admonition(node)


class TodolistDirective(Directive):
    def run(self):
        return [todolist('')]


class TodoDirective(SphinxDirective):
    # this enables content in the directive
    has_content = True

    def run(self):
        targetid = 'todo-%d' % self.env.new_serialno('todo')
        targetnode = nodes.target('', '', ids=[targetid])

        todo_node = todo('\n'.join(self.content))
        todo_node += nodes.title(_('Todo'), _('Todo'))
        todo_node += self.parse_content_to_nodes()

        if not hasattr(self.env, 'todo_all_todos'):
            self.env.todo_all_todos = []

        self.env.todo_all_todos.append({
            'docname': self.env.docname,
            'lineno': self.lineno,
            'todo': todo_node.deepcopy(),
            'target': targetnode,
        })

        return [targetnode, todo_node]


def purge_todos(app, env, docname):
    if not hasattr(env, 'todo_all_todos'):
        return

    env.todo_all_todos = [
        todo for todo in env.todo_all_todos if todo['docname'] != docname
    ]


def merge_todos(app, env, docnames, other):
    if not hasattr(env, 'todo_all_todos'):
        env.todo_all_todos = []
    if hasattr(other, 'todo_all_todos'):
        env.todo_all_todos.extend(other.todo_all_todos)


def process_todo_nodes(app, doctree, fromdocname):
    if not app.config.todo_include_todos:
        for node in doctree.findall(todo):
            node.parent.remove(node)

    # Replace all todolist nodes with a list of the collected todos.
    # Augment each todo with a backlink to the original location.
    env = app.builder.env

    if not hasattr(env, 'todo_all_todos'):
        env.todo_all_todos = []

    for node in doctree.findall(todolist):
        if not app.config.todo_include_todos:
            node.replace_self([])
            continue

        content = []

        for todo_info in env.todo_all_todos:
            para = nodes.paragraph()
            filename = env.doc2path(todo_info['docname'], base=None)
            description = _(
                '(The original entry is located in %s, line %d and can be found '
            ) % (filename, todo_info['lineno'])
            para += nodes.Text(description)

            # Create a reference
            newnode = nodes.reference('', '')
            innernode = nodes.emphasis(_('here'), _('here'))
            newnode['refdocname'] = todo_info['docname']
            newnode['refuri'] = app.builder.get_relative_uri(
                fromdocname, todo_info['docname']
            )
            newnode['refuri'] += '#' + todo_info['target']['refid']
            newnode.append(innernode)
            para += newnode
            para += nodes.Text('.)')

            # Insert into the todolist
            content.extend((
                todo_info['todo'],
                para,
            ))

        node.replace_self(content)


def setup(app: Sphinx) -> ExtensionMetadata:
    app.add_config_value('todo_include_todos', False, 'html')

    app.add_node(todolist)
    app.add_node(
        todo,
        html=(visit_todo_node, depart_todo_node),
        latex=(visit_todo_node, depart_todo_node),
        text=(visit_todo_node, depart_todo_node),
    )

    app.add_directive('todo', TodoDirective)
    app.add_directive('todolist', TodolistDirective)
    app.connect('doctree-resolved', process_todo_nodes)
    app.connect('env-purge-doc', purge_todos)
    app.connect('env-merge-info', merge_todos)

    return {
        'version': '0.1',
        'env_version': 1,
        'parallel_read_safe': True,
        'parallel_write_safe': True,
    }

这比在使用角色和指令扩展语法中详细介绍的扩展更广泛，但是，我们将一步一步地查看每个部分来解释正在发生的事情。

节点类

让我们从节点类开始

class todo(nodes.Admonition, nodes.Element):
    pass


class todolist(nodes.General, nodes.Element):
    pass


def visit_todo_node(self, node):
    self.visit_admonition(node)

节点类通常不需要做任何事情，除了继承自 docutils.nodes 中定义的标准 docutils 类。 todo 继承自 Admonition，因为它应该像注释或警告一样处理，todolist 只是一个“通用”节点。

注意

许多扩展不需要创建自己的节点类，并且可以使用 docutils 和 Sphinx 已提供的节点。

注意

重要的是要知道，虽然您可以在不离开 conf.py 的情况下扩展 Sphinx，但如果您在那里声明一个继承的节点，您将遇到一个不明显的 PickleError。因此，如果出现问题，请确保将继承的节点放入单独的 Python 模块中。

有关更多详细信息，请参阅

指令类

指令类通常是继承自 docutils.parsers.rst.Directive 的类。指令接口在 docutils 文档中也有详细介绍；重要的是，该类应具有配置允许标记的属性，以及一个 run 方法，该方法返回一个节点列表。

首先看看 TodolistDirective 指令

class TodolistDirective(Directive):
    def run(self):

它非常简单，创建并返回我们 todolist 节点类的实例。 TodolistDirective 指令本身既没有内容也没有参数需要处理。这让我们想到了 TodoDirective 指令

class TodoDirective(SphinxDirective):
    # this enables content in the directive
    has_content = True

    def run(self):
        targetid = 'todo-%d' % self.env.new_serialno('todo')
        targetnode = nodes.target('', '', ids=[targetid])

        todo_node = todo('\n'.join(self.content))
        todo_node += nodes.title(_('Todo'), _('Todo'))
        todo_node += self.parse_content_to_nodes()

        if not hasattr(self.env, 'todo_all_todos'):
            self.env.todo_all_todos = []

        self.env.todo_all_todos.append({
            'docname': self.env.docname,
            'lineno': self.lineno,
            'todo': todo_node.deepcopy(),
            'target': targetnode,
        })

        return [targetnode, todo_node]

这里涵盖了几个重要事项。首先，如您所见，我们现在正在子类化 SphinxDirective 辅助类，而不是通常的 Directive 类。这让我们可以使用 self.env 属性访问构建环境实例。如果没有它，我们将不得不使用相当复杂的 self.state.document.settings.env。然后，为了充当链接目标（来自 TodolistDirective），TodoDirective 指令需要返回一个目标节点，除了 todo 节点。目标 ID（在 HTML 中，这将是锚点名称）是通过使用 env.new_serialno 生成的，该方法在每次调用时都会返回一个新的唯一整数，因此会导致唯一的目标名称。目标节点在没有任何文本的情况下实例化（前两个参数）。

在创建警示节点时，指令的内容主体使用 self.state.nested_parse 进行解析。第一个参数给出内容主体，第二个参数给出内容偏移量。第三个参数给出解析结果的父节点，在本例中为 todo 节点。在此之后，todo 节点被添加到环境中。这对于能够在作者放置 todolist 指令的位置创建整个文档中所有待办事项条目的列表是必需的。对于这种情况，使用环境属性 todo_all_todos（同样，名称应该唯一，因此以扩展名称为前缀）。它在创建新环境时不存在，因此指令必须检查并在必要时创建它。有关待办事项条目位置的各种信息与节点副本一起存储。

在最后一行，返回应该放入 doctree 中的节点：目标节点和警示节点。

指令返回的节点结构如下所示

+--------------------+
| target node        |
+--------------------+
+--------------------+
| todo node          |
+--------------------+
  \__+--------------------+
     | admonition title   |
     +--------------------+
     | paragraph          |
     +--------------------+
     | ...                |
     +--------------------+

事件处理程序

事件处理程序是 Sphinx 最强大的功能之一，提供了一种将任何部分挂接到文档过程的方法。Sphinx 本身提供了许多事件，如 API 指南中所述，我们将在此处使用其中的一部分。

让我们看看上述示例中使用的事件处理程序。首先，是用于 env-purge-doc 事件的事件处理程序

def purge_todos(app, env, docname):
    if not hasattr(env, 'todo_all_todos'):
        return

    env.todo_all_todos = [
        todo for todo in env.todo_all_todos if todo['docname'] != docname

由于我们从源文件中存储的信息保存在环境中，而环境是持久性的，因此当源文件发生变化时，这些信息可能变得过时。因此，在读取每个源文件之前，都会清除环境中关于该文件的记录，并且 env-purge-doc 事件为扩展提供了相同的机会。在这里，我们将从 todo_all_todos 列表中清除所有与给定文档名匹配的待办事项。如果文档中仍然存在待办事项，它们将在解析期间再次添加。

下一个处理程序是针对 env-merge-info 事件的。它在并行构建期间使用。由于在并行构建期间，所有线程都有自己的 env，因此存在多个需要合并的 todo_all_todos 列表。

def merge_todos(app, env, docnames, other):
    if not hasattr(env, 'todo_all_todos'):
        env.todo_all_todos = []
    if hasattr(other, 'todo_all_todos'):

另一个处理程序属于 doctree-resolved 事件。

def process_todo_nodes(app, doctree, fromdocname):
    if not app.config.todo_include_todos:
        for node in doctree.findall(todo):
            node.parent.remove(node)

    # Replace all todolist nodes with a list of the collected todos.
    # Augment each todo with a backlink to the original location.
    env = app.builder.env

    if not hasattr(env, 'todo_all_todos'):
        env.todo_all_todos = []

    for node in doctree.findall(todolist):
        if not app.config.todo_include_todos:
            node.replace_self([])
            continue

        content = []

        for todo_info in env.todo_all_todos:
            para = nodes.paragraph()
            filename = env.doc2path(todo_info['docname'], base=None)
            description = _(
                '(The original entry is located in %s, line %d and can be found '
            ) % (filename, todo_info['lineno'])
            para += nodes.Text(description)

            # Create a reference
            newnode = nodes.reference('', '')
            innernode = nodes.emphasis(_('here'), _('here'))
            newnode['refdocname'] = todo_info['docname']
            newnode['refuri'] = app.builder.get_relative_uri(
                fromdocname, todo_info['docname']
            )
            newnode['refuri'] += '#' + todo_info['target']['refid']
            newnode.append(innernode)
            para += newnode
            para += nodes.Text('.)')

            # Insert into the todolist
            content.extend((
                todo_info['todo'],

在阶段 3 (解析) 结束时会发出 doctree-resolved 事件，它允许进行自定义解析。我们为该事件编写的处理程序稍微复杂一些。如果 todo_include_todos 配置值（我们将在后面介绍）为 false，则所有 todo 和 todolist 节点将从文档中移除。否则，todo 节点将保持原样。 todolist 节点将被一个待办事项条目列表替换，该列表包含指向其来源位置的回溯链接。列表项由来自 todo 条目的节点和动态创建的 docutils 节点组成：每个条目一个段落，包含提供位置的文本，以及一个带有回溯链接的链接（包含斜体节点的引用节点）。引用 URI 由 sphinx.builders.Builder.get_relative_uri() 构建，它根据使用的构建器创建适当的 URI，并将待办事项节点（目标）的 ID 作为锚点名称追加。

setup 函数

如前面所述，setup 函数是必需的，用于将指令插入 Sphinx。但是，我们还使用它来连接扩展的其他部分。让我们看一下我们的 setup 函数

        node.replace_self(content)


def setup(app: Sphinx) -> ExtensionMetadata:
    app.add_config_value('todo_include_todos', False, 'html')

    app.add_node(todolist)
    app.add_node(
        todo,
        html=(visit_todo_node, depart_todo_node),
        latex=(visit_todo_node, depart_todo_node),
        text=(visit_todo_node, depart_todo_node),
    )

    app.add_directive('todo', TodoDirective)
    app.add_directive('todolist', TodolistDirective)
    app.connect('doctree-resolved', process_todo_nodes)
    app.connect('env-purge-doc', purge_todos)
    app.connect('env-merge-info', merge_todos)

    return {
        'version': '0.1',
        'env_version': 1,
        'parallel_read_safe': True,
        'parallel_write_safe': True,
    }

此函数中的调用引用了我们之前添加的类和函数。各个调用的作用如下

add_config_value() 让 Sphinx 知道它应该识别新的配置值 todo_include_todos，其默认值为 False（这也告诉 Sphinx 它是一个布尔值）。

如果第三个参数是 'html'，则如果配置值更改其值，HTML 文档将被完全重建。对于影响读取（构建阶段 1 (读取)）的配置值，需要这样做。
add_node() 向构建系统添加一个新的节点类。它还可以为每个支持的输出格式指定访问者函数。当新节点保留到阶段 4 (写入) 时，需要这些访问者函数。由于 todolist 节点总是在阶段 3 (解析) 中被替换，因此它不需要任何访问者函数。
add_directive() 添加一个新的指令，由名称和类指定。
最后，connect() 向第一个参数指定的事件添加一个事件处理程序。事件处理程序函数将使用几个参数调用，这些参数在事件文档中进行了描述。

这样，我们的扩展就完成了。

使用扩展¶

与之前一样，我们需要在 conf.py 文件中声明它，从而启用该扩展。这里需要两个步骤

使用 sys.path.append 将 _ext 目录添加到 Python 路径。这应该放在文件开头。
更新或创建 extensions 列表，并将扩展文件名添加到列表中

此外，我们可能希望设置 todo_include_todos 配置值。如上所述，它默认为 False，但我们可以显式设置它。

例如

import os
import sys

sys.path.append(os.path.abspath("./_ext"))

extensions = ['todo']

todo_include_todos = False

现在，您可以在整个项目中使用该扩展。例如

index.rst¶

Hello, world
============

.. toctree::
   somefile.rst
   someotherfile.rst

Hello world. Below is the list of TODOs.

.. todolist::

somefile.rst¶

foo
===

Some intro text here...

.. todo:: Fix this

someotherfile.rst¶

bar
===

Some more text here...

.. todo:: Fix that

因为我们已将 todo_include_todos 配置为 False，所以实际上不会看到 todo 和 todolist 指令的任何渲染结果。但是，如果我们将它切换为 true，我们将看到之前描述的输出。

进一步阅读¶

有关更多信息，请参阅 docutils 文档和 Sphinx API。

如果您希望在多个项目或与他人共享您的扩展，请查看第三方扩展部分。