让 Sphinx 检测对辅助配置/模板文件的更改答案

【问题标题】：Making Sphinx detect changes to auxiliary configuration/template files让 Sphinx 检测对辅助配置/模板文件的更改
【发布时间】：2026-02-02 03:00:01
【问题描述】：

我正在使用 Sphinx（v1.4.9，在 Windows 7 上使用 Python 3.5.1，64 位）编写启用了 MathJax 的文档集。我想定义自定义 LaTeX 命令来清理我的源代码，所以我通过添加 _templates\layout.html 来实现 this approach：

{% extends "!layout.html" %}
{% set script_files = script_files + ["_static/mjconf.js"] %}

并在_static\mjconf.js 中定义我的自定义命令：

MathJax.Hub.Config({
  TeX: {
    Macros: {
      dsetarr: ['{\\small \\textsf{#1 Array } \\mathsf{(#2)} }', 2],
      dsettype: ['{\\small \\textsf{#1}}', 1],
      mtt: ['{\\texttt{#1}}' ,1],
      sgn: ['{\\mathrm{sgn}#1}', 1]
    }
  }
});

这一切都很好。

然而，每当我编辑 mjconf.js 以添加新命令或修改现有命令时，Sphinx 不会识别出配置已更改，因此很简单make html 不会像编辑 conf.py 后那样重建文档。我必须在make html 之前make clean 才能看到更改这些自定义MathJax 命令的效果。

如何配置 Sphinx 以通过重建整个文档集来响应编辑的 mjconf.js，就像它对编辑的 conf.py 所做的那样？

【问题讨论】：

我不知道这是否可能。但是make clean html不解决问题吗？它确实重建了整个文档集。
@mzhn 不在 Windows 上。 Windows 的make.bat 一次只需要一个“make target”。

标签： python configuration python-sphinx

【解决方案1】：

有make html -a，但这不会反映文档中交叉引用的更新。不过，如果您没有交叉引用更新，这将是最快的选择。

还有make html -E，以防您也有必须更新的交叉引用。

最后是make clean html，它删除（清理）构建目录，如果你的makefile有它，然后再次构建HTML。

【讨论】：

我的 Windows make.bat 似乎只处理单个“make 目标”。这三个选项都不起作用：前两个只是做一个普通的make html；第三个是make clean 并停在那里。也许我需要硬着头皮弄清楚 v1.5 的升级？我上次尝试时它表现不佳。
进一步考虑，我应该能够编辑make.bat，以便它将任何进一步的参数直接传递给Sphinx builder....然后make html -E可能会起作用。我猜测 -a 不会足够深入地重新生成到配置中，但我会尝试一下。
是的，快速破解make.bat 将%2 添加到传递给sphinx-build 的选项可以很好地允许make html -a 和make html -E。两次调用都将我对mjconf.js 的更改合并到一起就好了。谢谢！（FWIW，我为 Sphinx 整理了一个 GitHub PR，它启用了多个 make 目标 (make clean html epub latex) 并传递了 ~arbitrary sphinx-build 参数，以造福后代。）

【解决方案2】：

为了将make html -E 之类的调用启用为recommended by Steve Piercy，我将make.bat 从这里更改为：

set BUILDDIR=build
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source
set I18NSPHINXOPTS=%SPHINXOPTS% source
if NOT "%PAPER%" == "" (
    set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
    set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
)

到这里：

set BUILDDIR=build
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source %2
set I18NSPHINXOPTS=%SPHINXOPTS% source
if NOT "%PAPER%" == "" (
    set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
    set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
)

唯一的变化是将%2 附加到初始化%ALLSPHINXOPTS% 的行中。

【讨论】：