基于GitHub Actions与Sphinx，如何配置Docstring生成上标？

方案1：直接使用Sphinx内置上标语法 #

无需额外扩展，在Docstring的类型描述里用Sphinx原生的上标标记替换^符号：

:param ne_0: 平均电子密度
:type ne_0: float, default: 1e24 m\ :sup:-3
生成的文档会自动将\ :sup:-3``转换为<sup>-3</sup>，输出符合预期格式。

方案2：自定义文本替换规则（适配通用Docstring风格） #

如果不想手动修改Docstring，可在Sphinx配置文件conf.py中添加自定义处理逻辑，自动识别^并转换为上标：

1. 打开项目的conf.py，添加以下代码：

from docutils import nodes

def convert_caret_to_sup(app, doctree, docname):
    for node in doctree.traverse(nodes.Text):
        raw_text = node.astext()
        # 替换所有^后接数字/符号的格式为上标
        processed_text = raw_text.replace("^-3", "<sup>-3</sup>")
        # 可按需扩展替换其他上标，比如^2、^+等
        if processed_text != raw_text:
            parent_node = node.parent
            parent_node.replace(node, nodes.raw(text=processed_text, format='html'))

def setup(app):
    app.connect('doctree-resolved', convert_caret_to_sup)

2. 重新触发文档生成（GitHub Actions会自动执行或本地运行sphinx-build），Docstring中的m^-3会自动转换为目标格式。

方案3：用MathJax渲染数学式上标 #

如果文档包含大量物理单位或数学表达式，推荐启用Sphinx的MathJax扩展，以更规范的方式渲染上标：

1. 在conf.py的扩展列表中添加：

extensions = [
    # 已有的其他扩展
    'sphinx.ext.mathjax',
]

2. 修改Docstring为数学表达式格式：

:param ne_0: 平均电子密度
:type ne_0: float, default: 1e24 :math:m^{-3}
生成的文档会渲染出标准的数学上标，适合复杂公式场景。

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