如何通过API在Sphinx/docutils创建新文档？VHDL扩展需求

核心问题解答 #

1. 如何为每个VHDL构造生成独立HTML文件？ #

你可以直接通过Sphinx的环境API创建并注册docutils文档对象，无需经过ReST文件中转：

• 选择合适钩子时机：在扩展的env-before-read-docs或builder-inited事件钩子中执行文档创建逻辑。
• 手动构建文档树：利用已有的CodeDOM和docutils节点生成能力，为每个VHDL构造（实体、架构、包等）创建独立的docutils.nodes.document实例，直接填充对应的内容节点（标题、参数列表、注释段落等）。
• 注册文档到Sphinx环境：调用Sphinx环境对象的add_doc()方法，传入唯一的文档路径（比如vhdl/entities/uart_tx）和你构建好的document对象。这个路径会对应最终生成的HTML文件路径（如vhdl/entities/uart_tx.html）。
• 更新待处理文档列表：在env-updated钩子中，将新增的文档路径添加到env.found_docs集合中，确保Sphinx的Builder会处理这些文档。

2. 是否必须采用生成ReST文件的方式？ #

完全不需要。autoapi的ReST生成方式是为兼容没有直接操作docutils节点能力的场景设计的，而你已经具备解析VHDL到CodeDOM、生成docutils节点的能力，直接操作Sphinx环境和文档树是更高效的方案——既避免了序列化ReST再解析的冗余步骤，也能减少潜在的格式转换问题。

关键代码示例 #

from docutils.nodes import document, section, title
from sphinx.application import Sphinx

def setup(app: Sphinx):
    app.connect('env-before-read-docs', create_vhdl_docs)
    app.connect('env-updated', update_doc_list)

def create_vhdl_docs(app: Sphinx, env, docnames):
    # 假设你已经有了解析好的VHDL构造列表
    vhdl_constructs = get_parsed_vhdl_constructs()
    
    for construct in vhdl_constructs:
        # 创建docutils文档根节点
        doc = document()
        # 添加标题节点
        sect = section()
        sect += title(text=f"VHDL {construct.type}: {construct.name}")
        doc += sect
        
        # 这里添加你生成的其他内容节点（比如参数列表、注释等）
        doc += generate_construct_details(construct)
        
        # 注册文档到环境，指定唯一文档名
        doc_name = f"vhdl/{construct.type}s/{construct.name}"
        env.add_doc(doc_name, doc)
        
        # 缓存文档名，后续更新待处理列表
        if not hasattr(env, 'vhdl_docs'):
            env.vhdl_docs = []
        env.vhdl_docs.append(doc_name)

def update_doc_list(app: Sphinx, env):
    if hasattr(env, 'vhdl_docs'):
        env.found_docs.update(env.vhdl_docs)

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