为自定义指令的节点生成标签

Question

使用 Sphinx "TODO" Directive example 我想引用嵌入在 .rst 文件中的 todo 实例。例如，如果 .rst 文件内容包含：

.. todo:: foo

.. todo:: bar

我可以看到以下代码（取自 Sphinx TODO 示例页面）

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]

使用 ids 创建目标节点：todo-0 和 todo-1。通过在 .rst 文件中嵌入指令成功引用：

.. todolist::

我想做的是像这样在 .rst 文件中引用 todo 项：

:ref:`todo-0`
:ref:`todo-1`

这需要让 TodoDirective 为每个目标节点生成一个标签。我还不知道该怎么做。

这个简单的项目发布在这里：https://github.com/natersoz/sphinx_sandbox

Answer 1

我找到了一种执行此操作的方法。它可能只适用于 HTML 输出：

`Text related to todo-0 <introduction.html#todo-0>`_

此引用 link 将成功 link 到 TODO。所有其他参考尝试均失败。即这些都失败了：

Note: these syntaxes do not work::

    `introduction.html#todo-1`_

    :ref:`introduction.html#todo-1`

    :ref:`todo-1`

Answer 2

我遇到了与您相同的问题，并且能够通过查看 autosectionlabel 扩展来解决问题。

他们所做的是添加对标签域数据的引用。我让它在自定义指令中工作，如下所示：

nodeId = nodes.make_id("some-id")
self.env.app.env.domaindata["std"]["labels"][nodeId] = self.env.docname, nodeId, "Title"
section = nodes.section(ids=[nodeId])
section.append(nodes.title(text="Title"))

关键是上面代码的第二行。

您还想将标签添加到 anonlabels 以便能够通过

引用它

:ref:`foo <nodeId>`

像这样：

self.env.app.env.domaindata["std"]["anonlabels"][nodeId] = self.env.docname, nodeId

为自定义指令的节点生成标签

Generating labels for nodes of a custom directive

python

docutils

python-sphinx