python - 狮身人面像: how to cross-reference a target generated by a custom directive

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

这是指令:

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)

我该如何进行这项工作？

最佳答案

您似乎混淆了引用标签和指令的功能。
为了使术语更清楚，请在您的标记中:

工作的部分在reference label(带有装饰性下划线的“.. _section2:”)正前方有一个section title(section2)。这提供了可以通过interpreted text role(:ref:`section2`)链接到的目标。那是常规的Sphinx样板。

无效的部分具有您的自定义指令(.. mytest::)和其单个必需参数(section1)，并且没有内容块(该指令后没有缩进文本)。

行“Section 1 content.”是一个独立的段落。

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

编辑:ref:角色用于任意位置(“labels”，无论什么意思)
但您也可以通过: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表明所有这些功能的文献不多。

关于python - 狮身人面像: how to cross-reference a target generated by a custom directive，我们在Stack Overflow上找到一个类似的问题：https://stackoverflow.com/questions/61369600/