Sphinx：如何交叉引用由自定义指令生成的目标

Question

我在交叉引用由自定义指令生成的节时遇到麻烦。

这里是指令：

from docutils import nodes
from docutils.parsers import rst


class TestDirective(rst.Directive):

    has_content = False
    required_arguments = 1
    option_spec = {}

    def run(self):
        my_arg = self.arguments[0]

        target_node = nodes.target('', '', refid=nodes.make_id(my_arg))
        section = nodes.section(
            '',
            nodes.title(text=my_arg),
            ids=[nodes.make_id(my_arg)],
            names=[nodes.fully_normalize_name(my_arg)])

        return [target_node, section]


def setup(app):
   app.add_directive('mytest', TestDirective)

这是它的用法：

=============
Test document
=============

.. mytest:: section1

Section 1 content.


.. _section2:

section2
========

Section 2 content.

现在，以下仅适用于section2：

Here are links to :ref:`section1` and :ref:`section2`.

仅针对section2正确生成了链接，但出现以下错误：

test.rst:19: WARNING: undefined label: section1 (if the link has no caption the
label must precede a section header)

我该如何进行这项工作？

Answer 1

您似乎混淆了参考标签与指令的功能。

为了使术语更清晰，在您的标记中：

• [正在工作的零件在reference label（带下划线的“ .. _section2:”之前）直接具有section title（section2）。这提供了可以通过interpreted text role（:ref:`section2`）链接到的目标。那是常规的Sphinx样板。
• 无效的部分具有您的自定义指令（.. mytest::）及其单个必需参数（section1），并且没有内容块（指令后没有缩进文本）。>>
• Section 1 content.行是一个独立的段落。

也许您想要一个自定义的解释性文本角色来提供特殊功能，roles.XRefRole子类或autosectionlabel extension？