如何读取JSON/XML/YAML数据导入Sphinx RST文件自动生成文档页面

以下两种方案均可实现需求，可根据使用场景选择：

方案1：使用sphinx-jinja扩展（适合复杂数据渲染场景） #

该方案支持完整的模板语法，适合需要批量渲染、做条件判断的场景

1. 安装依赖
   pip install sphinx-jinja
2. 配置conf.py
   在Sphinx项目的conf.py中添加如下配置：

import json
import os

# 加载你的数据文件，这里以JSON为例
data_path = os.path.join(os.path.dirname(__file__), "data", "myfile.json")
with open(data_path, "r", encoding="utf-8") as f:
    zoo_data = json.load(f)

# 启用sphinx-jinja扩展，原有扩展保留
extensions = [
    # 你之前配置的其他扩展
    "sphinx_jinja"
]

# 配置Jinja全局上下文，把数据注入模板
jinja_contexts = {
    # 键名是你在RST中调用的变量名，值是加载好的数据
    "zoo_info": zoo_data
}

3. 编写RST文件
   直接在RST中使用Jinja语法引用对应字段即可，示例tiger.rst内容：

Tiger
=======================================

Tiger info here.

Species: 
{{ zoo_info.animals.tiger.species }}

Weight: 
{{ zoo_info.animals.tiger.weight }} kg

注：你给出的示例JSON存在语法问题，animals字段应该是对象而不是数组，调整为"animals": {}即可正常解析

方案2：自定义RST角色（适合轻量字段引用场景） #

如果只需要零散引用单个字段，不需要复杂模板逻辑，可以直接在conf.py中自定义专属引用角色，无需额外安装扩展：

1. 在conf.py末尾添加如下代码：

import json
import os
from docutils import nodes

# 预加载数据文件
data_path = os.path.join(os.path.dirname(__file__), "data", "myfile.json")
with open(data_path, "r", encoding="utf-8") as f:
    zoo_data = json.load(f)

def zoo_data_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
    # 按点分割字段路径，逐层取值
    keys = text.split(".")
    value = zoo_data
    try:
        for k in keys:
            value = value[k]
    except KeyError:
        return [nodes.Text(f"[数据不存在:{text}]")], []
    return [nodes.Text(str(value))], []

def setup(app):
    # 注册名为zoo的角色
    app.add_role("zoo", zoo_data_role)

2. 在RST中引用字段
   使用:zoo:字段路径的格式直接调用即可，示例tiger.rst`内容：

Tiger
=======================================

Tiger info here.

Species: 
:zoo:`animals.tiger.species`

Weight: 
:zoo:`animals.tiger.weight` kg

如果是YAML格式数据，只需要把JSON读取逻辑替换为PyYAML的解析逻辑即可；XML格式数据则可以用xml.etree模块解析后按需封装取值逻辑即可。

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