如何创建自动为引用创建标签的 Sphinx 角色？

问题描述

在我的文档中，我经常提到 XML 标签。所以我尝试编写一个小的扩展来简化向文档添加和引用标签的过程。文档应如下所示：

My text,referencing to :xmltag-ref:`ExampleTag` here.

The :xmltag:`ExampleTag` Explained in Detail
--------------------------------------------

This section describes the tag...

我写了一个这样的简单扩展：

import re
from docutils import nodes

def xmltag(name,rawtext,text,lineno,inliner,options={},content=[]):
    literal_node = nodes.literal(text=text,classes=['xmltag'])
    # <--- HERE: How to add target?
    result_nodes = [literal_node]
    return result_nodes,[]

def xmltag_ref(name,content=[]):
    source = f'tag-{text}'
    reference_node = nodes.reference(classes=['xmltag-ref'],text=text)
    reference_node['refid'] = source
    result_nodes = [reference_node]
    return result_nodes,[]

def setup(app):
    app.add_role("xmltag-ref",xmltag_ref)
    app.add_role("xmltag",xmltag)

    return {
        'version': '1.0','parallel_read_safe': True,'parallel_write_safe': True,}

如果我手动添加引用，一切都会按预期进行，但是如果在标题中定义了标签，我找不到如何自动添加标签的方法。

我喜欢自动引用的工作方式，例如使用 option 指令：

.. option:: --example

    text...

这会自动创建一个标签，可以使用 :option:'--example' 引用。我想要类似的东西，但可以灵活地在标题中使用它，这也会在 TOC 中创建一个条目。

如何在角色元素中添加标签？

或者，还有其他方法，应该如何正确解决？

解决方法

暂无找到可以解决该程序问题的有效方法，小编努力寻找整理中！

如果你已经找到好的解决方法，欢迎将解决方案带上本链接一起发送给小编。

小编邮箱:dio#foxmail.com (将#修改为@）

python python-sphinx restructuredtext