python - 如何在 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`

项目中的任何位置。