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

您似乎混淆了引用标签和指令的功能。

要清楚术语，请在您的标记中：

• 有效的部分在section title（带有装饰下划线的“section2”）之前有一个reference label（.. _section2:）。这提供了一个可以通过interpreted text role (:ref:`section2`) 链接的目标。这是常规的 Sphinx 样板。
• 不起作用的部分是您的自定义指令 (.. mytest::) 和它的单个必需参数 (section1) 并且没有内容块（指令后面没有缩进文本）。
• “Section 1 content.”行是一个独立的段落。

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

---

编辑

:ref: 角色适用于任意位置（“标签”，无论是什么意思） 但你也可以通过:any:once it is registered交叉引用自定义对象：

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

    app.add_object_type(
        directivename='mytest',
        rolename='banana',
    )

然后是 ReST 内容：

See :any:`section1` which is a TestDirective.

Or also works via the rolename :banana:`section1`.

Many would agree 所有这些功能都没有很好的记录。