如何在文档中内联插入程序生成的变量内容？替代块级.. exec::指令

架构老林

2026-7-21

Sphinx内联动态插入程序生成数值的实现方法

在Sphinx中，要实现内联从模块读取动态数值的需求，有几种可行方案：

使用eval-rst指令结合替换标记：
你可以用.. eval-rst::块包裹包含替换标记的内容，让Sphinx在构建时自动替换模块中的数值，示例如下：
```
.. eval-rst::
   本模块使用 |c| m/s作为光速常量

   .. |c| replace:: {{ your_module.C }}
```
这里your_module.C是你模块中存储光速常量的变量，构建文档时会被替换为实际数值。

自定义内联exec角色：
若需要更灵活的内联调用，可编写简单的Sphinx扩展实现内联执行功能。比如创建一个扩展文件，写入以下代码：

from docutils import nodes
from docutils.parsers.rst import directives

def inline_exec_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
    try:
        # 直接执行代码片段，获取结果
        result = eval(text)
        return [nodes.Text(str(result))], []
    except Exception as e:
        msg = inliner.reporter.error(f"内联执行出错: {str(e)}", line=lineno)
        return [inliner.problematic(rawtext, rawtext, msg)], [msg]

def setup(app):
    app.add_role('exec', inline_exec_role)
    return {'version': '0.1', 'parallel_read_safe': True}

之后在conf.py中加载该扩展，就能在文档中用内联角色调用：

本模块使用 :exec:`your_module.C` m/s作为光速常量

启用Jinja2模板支持：
若你的Sphinx项目开启了Jinja2模板（在conf.py的extensions中添加sphinx.ext.templating），可直接用模板语法插入变量：
```
本模块使用 {{ your_module.C }} m/s作为光速常量
```
注意需要在conf.py中提前导入目标模块，比如添加import your_module，同时确保模块路径已加入sys.path。