如何在sphinx中创建可引用的标签节点

Question

我正在sphinx中创建一个自定义指令。 该指令列出了所有可能的对象（每个对象都在单独的部分中）。

现在我希望这些对象可以从文档的其他部分（文件）中引用。

我试图做一些非常简单的事情：

class MyDirective(Directive):
    def run(self, obj):
        id1 = 'object-unique-id1'
        id2 = 'object-unique-id2'
        label = nodes.label('abc1', refid=id1)
        section = nodes.section(ids=[id2])
        section += nodes.title(text='abc')
        section += label
        return [section]

但它不允许我通过以下方式引用此部分：ref：object-unique-id1，：ref：object-unique-id2或：ref：abc。

所以我的问题是：如何创建可以引用的节点？

Answer 1

在该部分出现之前立即添加目标。类似的东西：

class MyDirective(Directive):
    def run(self, obj):
        titleTxt = 'abc'
        lineno = self.state_machine.abs_line_number()
        target = nodes.target()
        section = nodes.section()

        # titleTxt appears to need to be same as the section's title text
        self.state.add_target(titleTxt, '', target, lineno) 
        section += nodes.title(titleTxt, '')

        return [target, section]

请注意对self.state.add_target的调用。

在构建中的某个地方，目标是神奇地创建的，并且应该能够使用

引用您的部分

:ref:`abc`

项目中的任何地方。