[SOLVED] Making Sphinx detect changes to auxiliary configuration/template files

Making Sphinx detect changes to auxiliary configuration/template files

I'm using Sphinx (v1.4.9, with Python 3.5.1 on Windows 7, 64-bit) to write a document set with MathJax enabled. I wanted to define custom LaTeX commands to clean up my source, so I implemented this approach by adding _templates\layout.html:

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

and defining my custom commands in _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]
    }
  }
});

This is all working great.

However, whenever I edit mjconf.js to add a new command or revise an existing one, Sphinx doesn't recognize that the configuration has changed and so a simple make html doesn't rebuild the docs like it does after an edit to conf.py. I have to make clean before the make html in order to see the effects of the changes to these custom MathJax commands.

How can I configure Sphinx to react to an edited mjconf.js by rebuilding the entire documentation set, just like it does for an edited conf.py?

Solution

There's make html -a, but that will not reflect updates to cross-references in your documentation. This would be the fastest option, though, if you have no cross-reference updates.

There's also make html -E in case you have cross-references that must be updated, too.

Finally there is make clean html, which deletes (cleans) the build directory, if your makefile has it, then builds HTML again.