如何在Sphinx中编程创建doctree并整合至文档体系？

当然可以跳过RST生成与解析步骤，直接构造docutils doctree并整合到Sphinx项目里——这是批量生成内容场景下优化性能的常用思路，能大幅减少IO开销和解析时间。下面是具体实现思路和代码示例：

核心实现路径 #

Sphinx的文档处理本质基于docutils的doctree，你完全可以在扩展中直接构造doctree节点，再注入到Sphinx的构建环境中，无需经过RST文件的读写和解析环节。

1. 手动构造docutils节点 #

先熟悉docutils的核心节点类型，比如document（根节点）、section（章节）、paragraph（段落）、literal_block（代码块）等，所有节点都来自docutils.nodes模块。

2. 在Sphinx扩展中注入Doctree #

通过Sphinx的事件钩子（比如env-before-read-docs或builder-inited），直接将构造好的doctree添加到Sphinx的构建环境(sphinx.environment.BuildEnvironment)中。

示例代码

from docutils import nodes
from sphinx.application import Sphinx
from sphinx.environment import BuildEnvironment

def add_doctree_to_env(app: Sphinx, env: BuildEnvironment, docnames):
    # 定义生成文档的名称（对应最终输出的文件名）
    new_docname = "generated_doctree"
    
    # 构造根文档节点
    doc = nodes.document()
    doc["source"] = "<generated>"  # 标记为生成内容，避免文件查找
    doc["docname"] = new_docname
    
    # 添加章节节点
    section = nodes.section()
    section += nodes.title(text="直接生成的Doctree章节")
    doc += section
    
    # 添加段落内容
    para = nodes.paragraph(text="这是通过docutils直接构造的段落，没有经过RST解析。")
    section += para
    
    # 添加代码块
    code_block = nodes.literal_block(text="print('Hello from direct doctree!')")
    code_block["language"] = "python"
    section += code_block
    
    # 将doctree添加到Sphinx环境
    env.add_doc(new_docname, doc)
    # 确保文档被包含在构建列表中
    if new_docname not in docnames:
        docnames.append(new_docname)

def setup(app: Sphinx):
    app.connect("env-before-read-docs", add_doctree_to_env)
    return {
        'version': '0.1',
        'parallel_read_safe': True,
    }

3. （可选）预生成并加载序列化的Doctree #

如果需要离线预生成doctree再导入，可以将构造好的节点序列化为pickle文件（Sphinx默认的doctree存储格式），然后在扩展中读取并注入环境：

import pickle

# 预生成时保存doctree
def save_doctree(doc, filepath):
    with open(filepath, 'wb') as f:
        pickle.dump(doc, f)

# 在Sphinx扩展中加载
def load_doctree(app: Sphinx, env: BuildEnvironment, docnames):
    new_docname = "pre_generated_doctree"
    with open("path/to/your/doctree.pickle", 'rb') as f:
        doc = pickle.load(f)
    doc["docname"] = new_docname
    env.add_doc(new_docname, doc)
    docnames.append(new_docname)

注意事项 #

• 节点属性要补全：source、docname等属性必须正确设置，否则Sphinx可能抛出警告或处理异常。
• 交叉引用处理：如果需要内部交叉引用，要手动为目标节点设置ids属性，并在引用节点中设置refid；或者用Sphinx的add_target方法注册目标。
• 自定义节点支持：如果用了自定义docutils节点，需要通过app.add_node方法在Sphinx中注册对应的转换器，否则构建时会报错。

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