如何用Python编写自定义Sphinx指令生成链接列表？

没问题，我帮你实现一个自定义Sphinx指令，直接在构建过程中生成目标链接列表，完全替代原来依赖.. include:: other_file.rst的方式。下面是完整的解决方案：

1. 编写指令代码 #

你可以把以下代码直接添加到Sphinx项目的conf.py中，或者创建单独的扩展文件（比如custom_extensions.py），再在conf.py里通过extensions.append("custom_extensions")加载：

from docutils import nodes
from docutils.parsers.rst import Directive

# 这里存放你的链接数据，也可以从外部配置/文件读取
TARGET_LINKS = [
    ("Text Item 1", "https://link/to/somewhere"),
    ("Text Item 2", "https://link/to/somewhere_else"),
    # 后续可以随时添加更多条目
]

class DynamicLinkList(Directive):
    # 指令不需要传入参数
    required_arguments = 0
    optional_arguments = 0
    has_content = False

    def run(self):
        # 创建无序列表节点
        bullet_list = nodes.bullet_list()
        
        for link_text, link_url in TARGET_LINKS:
            # 创建单个列表项
            list_item = nodes.list_item()
            # 创建带链接的文本节点
            link_node = nodes.reference(link_text, link_text, refuri=link_url)
            # 把链接添加到列表项，再把列表项添加到总列表
            list_item.append(link_node)
            bullet_list.append(list_item)
        
        # 返回生成的节点树
        return [bullet_list]

# 注册自定义指令到Sphinx
def setup(app):
    app.add_directive("dynamic_link_list", DynamicLinkList)
    return {
        "version": "0.1",
        "parallel_read_safe": True,
        "parallel_write_safe": True,
    }

2. 在RST文件中使用指令 #

现在你可以直接用这个指令替换原来的include语句：

.. dynamic_link_list::

执行sphinx-build时，这个指令会自动生成和原来other_file.rst完全一致的带链接无序列表。

3. 灵活扩展（可选） #

如果希望链接数据可以动态配置，比如从指令内容传入，你可以修改指令类：

class DynamicLinkList(Directive):
    # 允许指令包含内容
    has_content = True

    def run(self):
        bullet_list = nodes.bullet_list()
        # 解析每一行内容，格式为「文本|链接」
        for line in self.content:
            line = line.strip()
            if not line:
                continue
            text_part, url_part = line.split("|", 1)
            link_text = text_part.strip()
            link_url = url_part.strip()
            
            list_item = nodes.list_item()
            link_node = nodes.reference(link_text, link_text, refuri=link_url)
            list_item.append(link_node)
            bullet_list.append(list_item)
        
        return [bullet_list]

对应的使用方式变成：

.. dynamic_link_list::
    Text Item 1 | https://link/to/somewhere
    Text Item 2 | https://link/to/somewhere_else

这种方式不用在代码里硬编码链接，修改起来更灵活。

方案优势 #

• 不需要再维护额外的other_file.rst文件，减少冗余
• 链接数据可以集中管理，修改更高效
• 支持后续扩展动态生成（比如从数据库/配置文件拉取链接）

内容的提问来源于stack exchange，提问作者tonyb