Sphinx公式编号与交叉引用失效及章节自动编号配置咨询

你碰到的核心问题是手动添加的章节编号无法被Sphinx的numfig系统识别——Sphinx的公式编号功能依赖它自动生成的章节结构编号，手动写的1.、1.1这类标记对它来说只是普通文本，所以公式没法关联到章节，自然不会显示编号（但交叉引用的label是有效的，所以链接能正常跳转）。

下面是具体的修复步骤：

1. 移除手动章节编号 #

先把测试文件里手动加的章节序号删掉，让Sphinx自动处理编号：

修改后的测试文件1： #

Test File 1 Main
=============
Inline math examples: :math:`\color{blue}{\sigma_{1}}` equals :math:`\colorbox{yellow}{\sigma_{2}}` then etc, etc. Any text.

.. math:: x^2+y^2=1
:label: eq_a

Math block example with label:

.. math:: e^{i\pi} + 1 = 0
:label: eq_b

Some Examples
****************

.. math:: \color{red}{x^2}+y^2=3
:label: eq_c

修改后的测试文件2： #

Test File 2 Main
=============
Refer to :eq:`eq_a`
Refer to :eq:`eq_b`
Refer to :eq:`eq_c`

2. 完善conf.py的配置 #

确保你的conf.py里包含以下配置（已经有的可以保留，补充缺失的）：

numfig = True
math_numfig = True
numfig_secnum_depth = 2  # 公式编号会关联到2级章节（比如 Eq.1.1、Eq.1.2）
math_eqref_format = "Eq.{number}"
# 开启自动章节编号，让Sphinx给标题生成序号
html_secnumbered_subsections = True
# 可选：控制目录中显示的编号深度
toc_secnum_depth = 2

3. 重新生成HTML #

执行你的Sphinx构建命令（比如make html），现在公式应该会显示带章节前缀的编号，交叉引用也会正确渲染成对应的编号文本（比如Eq.1.1）。

额外说明 #

如果不想让章节显示编号，只想要公式的全局连续编号，可以把numfig_secnum_depth设为0，这样公式会被编号为Eq.1、Eq.2……但即使这样，也必须移除手动章节编号，让Sphinx能正确解析文档的层级结构，公式编号才能正常生成。

内容的提问来源于stack exchange，提问作者Ralph B.