Sphinx System Issues

Crash building CHM file in HTML Help

HTML Help Workshop has problems with long paths. Check this if there is a crash at the build chm step during a “make htmlhelp” run.

Installation

See \tetleys\programs\sphinx_system_components. The file “notes(simple).txt” provides instructions on the setting up the core components of the system.

Notes

• Currently using Sphinx 1.2.3. When doing a build, the version is reported at the start of output, so you can check it then.
• Currently tied to miktex 2.9.4813 (32 or 64 bit version). This is the ONLY version of MikTex that we have been able to use that will generate png images for math correctly. Other versions do not produce the png images – and this is an unexplained mystery.
• Almost everyone uses Notepad++ for editing RST files. The extension reStructuredText_NPP-master.zip (readme.rst has install instructions) can be used to provide a so-so sphinx syntax highlighter, which is probably better than nothing.

Math

The MathJax extension is used to obtain mathematics in Itasca’s Sphinx documentation. See http://www.mathjax.org. The details of our implementation are as follows.

• in conf.py, two bits are required:
  • sphinx.ext.mathjax is added to the list of extensions
  • the string mathjax_path = 'MathJax/MathJax.js?config=TeX-AMS_SVG'   #for local library appears on a line by itself

The first line simply indicates to Sphinx that the MathJax extension will be turned on and used (as is needed for any extension being implemented with Sphinx). The second line does a lot of work. It indicates where to find the root MathJax file (the file “MathJax.js”); note a relative path is used, so the “_static” path is assumed. See xxxx topic for more info. Following the “?”, the part “config=TeX-AMS_SVG” indicates that mathematical input in RST files will take the form of TeX markup, and that output should be in SVG format.

• MathJax distribution

The full distribution for MathJax is > 60 Mb and has > 30K files in it. Because it lives in “_static”, all contents of the distribution are copied on any build. At full size, this is really really annoyingly time consuming. As a result, we are using a stripped down distribution. The distribution was created by following the instructions here [xxxxx] in piecemeal fashion (stip out part, build, on success continue, on failure restore that which was stripped out and try again); the resulting reduced distribution is < 3.5 Mb and < 150 files, and copies in seconds or less at the end of the build.

• the file “TeX-AMD_SVG.js” file

This file is the base configuration file for the input-output we are using. Relative to the path named in the “mathjax_path” setting described above, it is found at “/MathJax/config/TeX-AMS_SVG.js”. In that file, in the “MathJax.Hub.Config” function it contains settings for SVG output that are wanted for ICG docs.

All of the above must be kept in mind if any attempt to update to a later MathJax is going to be made.

Citations

Maybe not the right place for this, but… If two different documents require the same citation in the endnotes, listing it the same way twice will produce errors. As a result, for now, a 2007 paper by Smith that needs to appear at the end of document A and at the end of document B should be cited as [Smith2007a] in doc A and as [Smith2007b] in doc B.