开发一个 “TODO” 插件¶

本教程的目的是创建一个比开发一个 “Hello world” 插件中创建的更全面的插件。那个指南只是涵盖了编写一个自定义的指令，而本指南增加了多个指令，以及自定义节点、额外的配置值和自定义事件处理程序。为此，我们将介绍 todo 插件，它可以在文档中加入 todo 项，并将其收集在一个中心位置。这与 Sphinx 的 sphinxext.todo 插件类似。

概述¶

注解

要了解这个插件的设计，请参考重要对象和构建阶段。

我们希望这个插件能给 Sphinx 增加以下内容:

一个 todo 指令，包含一些标有 “TODO” 的内容，只有在设置了新的配置值后才会在输出中显示。默认情况下，Todo 条目不应该出现在输出中。
一个 todolist 指令，创建了整个文档中所有 todo 条目的列表。

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

新指令，称为 todo 和 todolist。
新建文档树节点来代表这些指令，传统上也称为 todo 和 todolist。如果新指令只产生一些可由现有节点表示的内容，我们就不需要新的节点。
一个新的配置值 todo_include_todos （配置值的名字应该以扩展名开始，以便保持唯一），控制 todo 条目是否进入输出。
新的事件处理程序：一个用于 doctree-resolved 事件，以替换 todo 和 todolist 节点，一个用于 env-merge-info，以合并并行构建的中间结果，一个用于 env-purge-doc （其原因将在后面介绍）。

前提条件¶

和开发一个 “Hello world” 插件一样，我们不会通过 PyPI 发布这个插件，所以我们再次需要一个 Sphinx 项目来调用它。你可以使用现有的项目或使用 sphinx-quickstart 创建一个新项目。

我们假设你在使用独立的源文件（source）和构建文件（build）文件夹。你的扩展文件可以在你项目的任何文件夹中。在我们的例子中，让我们做以下事情：

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

下面是一个你可能获得的文件夹结构的例子：

└── 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.locale import _
from sphinx.util.docutils import SphinxDirective


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'))
        self.state.nested_parse(self.content, self.content_offset, todo_node)

        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.traverse(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.traverse(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, 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.append(todo_info['todo'])
            content.append(para)

        node.replace_self(content)


def setup(app):
    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',
        'parallel_read_safe': True,
        'parallel_write_safe': True,
    }

这比开发一个 “Hello world” 插件中详细介绍的扩展要广泛得多，然而，我们将逐步查看每一块，解释发生了什么。

节点类

让我们从节点类开始：

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)

节点类通常不需要做任何事情，除了继承 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):
        return [todolist('')]

这很简单，创建并返回我们的 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'))
        self.state.nested_parse(self.content, self.content_offset, todo_node)

        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 属性访问 build environment 实例。如果没有这个，我们将不得不使用相当复杂的 self.state.document.settings.env。然后，为了充当链接目标（来自 TodolistDirective ），TodoDirective 指令需要在 todo 节点之外返回一个目标节点。目标 ID（在 HTML 中，这将是锚的名称）是通过使用 env.new_serialno 来生成的，它在每次调用时都会返回一个新的唯一的整数，因此导致了唯一的目标名称。目标节点被实例化，没有任何文本（前两个参数）”

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

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

该指令返回的节点结构看起来像这样

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

事件处理者

Event handlers are one of Sphinx’s most powerful features, providing a way to do hook into any part of the documentation process. There are many events provided by Sphinx itself, as detailed in the API guide, and we’re going to use a subset of them here.

Let’s look at the event handlers used in the above example. First, the one for the env-purge-doc event:

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]

Since we store information from source files in the environment, which is persistent, it may become out of date when the source file changes. Therefore, before each source file is read, the environment’s records of it are cleared, and the env-purge-doc event gives extensions a chance to do the same. Here we clear out all todos whose docname matches the given one from the todo_all_todos list. If there are todos left in the document, they will be added again during parsing.

The next handler, for the env-merge-info event, is used during parallel builds. As during parallel builds all threads have their own env, there’s multiple todo_all_todos lists that need to be merged:

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)

The other handler belongs to the doctree-resolved event:

def process_todo_nodes(app, doctree, fromdocname):
    if not app.config.todo_include_todos:
        for node in doctree.traverse(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.traverse(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, 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.append(todo_info['todo'])
            content.append(para)

        node.replace_self(content)

The doctree-resolved event is emitted at the end of phase 3 (resolving) and allows custom resolving to be done. The handler we have written for this event is a bit more involved. If the todo_include_todos config value (which we’ll describe shortly) is false, all todo and todolist nodes are removed from the documents. If not, todo nodes just stay where and how they are. todolist nodes are replaced by a list of todo entries, complete with backlinks to the location where they come from. The list items are composed of the nodes from the todo entry and docutils nodes created on the fly: a paragraph for each entry, containing text that gives the location, and a link (reference node containing an italic node) with the backreference. The reference URI is built by sphinx.builders.Builder.get_relative_uri() which creates a suitable URI depending on the used builder, and appending the todo node’s (the target’s) ID as the anchor name.

The setup function

As noted previously, the setup function is a requirement and is used to plug directives into Sphinx. However, we also use it to hook up the other parts of our extension. Let’s look at our setup function:

def setup(app):
    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',
        'parallel_read_safe': True,
        'parallel_write_safe': True,
    }

The calls in this function refer to the classes and functions we added earlier. What the individual calls do is the following:

add_config_value() lets Sphinx know that it should recognize the new config value todo_include_todos, whose default value should be False (this also tells Sphinx that it is a boolean value).

If the third argument was 'html', HTML documents would be full rebuild if the config value changed its value. This is needed for config values that influence reading (build phase 1 (reading)).
add_node() adds a new node class to the build system. It also can specify visitor functions for each supported output format. These visitor functions are needed when the new nodes stay until phase 4 (writing). Since the todolist node is always replaced in phase 3 (resolving), it doesn’t need any.
add_directive() adds a new directive, given by name and class.
Finally, connect() adds an event handler to the event whose name is given by the first argument. The event handler function is called with several arguments which are documented with the event.

With this, our extension is complete.

Using the extension¶

As before, we need to enable the extension by declaring it in our conf.py file. There are two steps necessary here:

Add the _ext directory to the Python path using sys.path.append. This should be placed at the top of the file.
Update or create the extensions list and add the extension file name to the list

In addition, we may wish to set the todo_include_todos config value. As noted above, this defaults to False but we can set it explicitly.

For example:

import os
import sys

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

extensions = ['todo']

todo_include_todos = False

You can now use the extension throughout your project. For example:

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

Because we have configured todo_include_todos to False, we won’t actually see anything rendered for the todo and todolist directives. However, if we toggle this to true, we will see the output described previously.

目录

上一个主题

下一个主题

本页

开发一个 “TODO” 插件¶

概述¶

前提条件¶

编写插件¶

Using the extension¶

Further reading¶