如何在Sphinx中生成包含自定义域所有项的自定义索引页？

可行性确认 #

完全可行。Sphinx的扩展机制支持在你需求的时机生成自定义节点，同时保证交叉引用正常工作。

实现思路：利用后转换（Post-transform） #

你提到的env-merge-info事件完成后、引用解析完成但转换开始前的时机，正好对应Sphinx的**后转换（Post-transform）**阶段。这个阶段在文档解析完成、引用已解析，但还未将AST转换为最终输出格式时执行，完美匹配你的场景。

具体操作步骤 #

1. 定义自定义节点类型
   先创建继承自nodes.Element的自定义节点类：

from docutils import nodes

class CustomDomainItemNode(nodes.Element):
    pass

2. 编写后转换类
   创建继承自SphinxPostTransform的转换类，重写run方法来处理索引页的节点生成：

from sphinx.transforms.post_transforms import SphinxPostTransform
from sphinx import addnodes

class CustomDomainIndexTransform(SphinxPostTransform):
    # 设置优先级：推荐在引用解析之后、默认索引转换之前
    priority = 400

    def run(self, **kwargs):
        # 获取你的自定义domain（替换为实际domain名称）
        domain = self.app.env.domains.get('your_custom_domain')
        if not domain or not domain.data:
            return

        # 定位到你的类索引页文档（替换为实际文档名，比如custom_class_index）
        target_docname = 'custom_class_index'
        if target_docname not in self.app.env.all_docs:
            return
        
        doctree = self.app.env.get_doctree(target_docname)
        # 清空原有内容（按需选择，若要保留原有内容可跳过此步）
        doctree.clear()

        # 遍历domain.data生成自定义节点
        for item_key, item_info in domain.data.items():
            custom_node = CustomDomainItemNode()
            # 添加带交叉引用的节点
            ref_node = addnodes.pending_xref(
                reftype='your_ref_type',  # 替换为domain定义的引用类型
                reftarget=item_key,
                refdomain='your_custom_domain',
                refexplicit=True
            )
            ref_node += nodes.Text(item_info.get('display_name', item_key))
            custom_node += ref_node
            # 可添加更多自定义内容，比如描述文本、标签等
            if 'description' in item_info:
                custom_node += nodes.paragraph(text=item_info['description'])
            doctree += custom_node

3. 注册后转换与节点处理逻辑
   在扩展的setup函数中完成注册：

def visit_custom_item_node(self, node):
    self.body.append('<div class="custom-domain-item">')

def depart_custom_item_node(self, node):
    self.body.append('</div>')

def setup(app):
    # 注册后转换
    app.add_post_transform(CustomDomainIndexTransform)
    # 注册自定义节点的HTML转换逻辑（按需添加其他格式的处理）
    app.add_node(CustomDomainItemNode,
                html=(visit_custom_item_node, depart_custom_item_node))
    # 你的自定义domain注册代码...
    return {'version': '0.1', 'parallel_read_safe': True}

优先级推荐 #

后转换的优先级范围为0-1000，推荐设置为400：

• 低于默认索引转换的优先级（500），确保自定义节点生成在默认索引处理之前；
• 高于引用解析相关转换的优先级（通常200-300），保证引用已完成解析，pending_xref能正确映射到目标内容。

关键注意事项 #

• 确保自定义domain的merge_domaindata方法正确实现，并行构建时能完整合并多进程的data数据；
• 索引页的文档名需与代码中target_docname严格匹配，避免无法定位目标文档树；
• 引用类型reftype必须与domain中定义的引用类型一致，否则交叉引用会失效。

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