CODEWITHSUNDEEP
pythonconfigurationpython-sphinx
hBy2Py
hBy2Py

Reputation: 1832

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?

Upvotes: 5

Views: 595

Answers (2)

Steve Piercy
Steve Piercy

Reputation: 15035

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.

Upvotes: 2

hBy2Py
hBy2Py

Reputation: 1832

In order to enable invocations such as make html -E as recommended by Steve Piercy, I changed my make.bat from this:

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%
)

to this:

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%
)

The only change was appending %2 to the line initializing %ALLSPHINXOPTS%.

Upvotes: 0

Related Questions