Sphinx System Notes

Page Index

I. Customizations
      Command Tooltips
      Sphinx stdout crlfs
      Syntax highlighting
II. Extensions
      Mathjax
III. System Notes
      ICG Sphinx Docs

This page is a repository of descriptions of additions, modifications, or other extensions of the Sphinx environment. Some are conveniences, others are necessary for proper production of documentation. In addition, the page contains notes on aspects of the system that are otherwise undocumented or unapparent. Lastly, there are a random assortment of notes on markup usages/mistakes that will yield big trouble and tips on how to avoid them.

Direct Customizations to the Sphinx Package

Tooltips for Commands/FISH*

Files edited:

  • fish_domain.py

  • /common/trunk/python/python_env/python36/Lib/site-packages/docutils/writers/_html_base.py

ord('Þ'): '
', #icg add; used to insert line breaks

IMPORTANT! Above was added at line 196 of _html_base.py. What it does is swap in the html char code for a line break (
) wherever the þ character is encountered.

In the meantime, fish_domain.py was edited so that commands and FISH functions are listed on tables of one column (rather than two), and when the command first line/function description is “read” so that it can be returned to the “title” node (attribute) of the hyperlink for the command/function, a þ is inserted every 12 words. This puts line breaks in the tooltips that are created in the browser when mousing over a command or FISH function (as listed on the tables).

Carriage returns in Sphinx Standard Output*

Files edited:

  • /common/branches/pfc600/python/python_env/python36/Lib/site-packages/sphinx/builders/__init__.py

  • /common/branches/pfc600/python/python_env/python36/Lib/site-packages/sphinx/environment/__init__.py

Add \n in key spots in above files so output for
writing output... [ xx%] (in /builders/__init__.py)
and
reading sources... [ xx%] (in /environment/__init__.py)
has line breaks.

For example, line 437 of /builders/__init__.py:

for docname in status_iterator(docnames, '\nwriting output... ', "darkgreen",
                            len(docnames), self.app.verbosity):

There are three spots like the above in each file that require the edit.

Syntax Highlighting*

Syntax highlighting in the docs is a regex-based swipe at matching the code’s default syntax highlighting scheme — which is to say, most significantly, that it is completely independent of the code’s system and therefore certain to mis-highlight things, sooner or later.

The key parts are:

\common\python\python_env\python36\Lib\site-packages\pygments\styles\itasca.py

This file provides the colorization of identified syntax components, and is housed with the pygments package in the python distribution but is not a native file of it. This means it has to be emplaced “by hand” within a Python distribution that includes the “Pygments” package.

\common\docproject\extensions\itasca_lexer.py

This file defines the regexes that identify Itasca software command/FISH syntax parts; it does the heavy lifting.

Note 2/10/20: highlighting updated to include FLAC3D and 3DEC commands. Also, regexes for commands include the list of all subcommands, which should be more accurate over time (look at the list command_kw in the second file above).

Extensions in Use

Setting Up Math → MathJax

The MathJax extension is used to render equations and math 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.

to be complete, this section should indicate ALL extensions we add to base Sphinx extension

General System Notes

ICG Sphinx Documentation Notes

All docs that appear in this section are stored in the source folder:

/common/docproject/utility/sphinxnotes

After build and prior to distribution (whether that means inclusion in an MSI file or being uploaded to wherever currently publicly available (as of July 2020 that is from an Amazon AWS S3 bucket)) this folder should be deleted.

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.

Ways to Crash Sphinx

  • If you build a local (in file) substitution that uses a substitution (for example, “margie” below)

    .. |willerr| replace:: no def for |margie| yet

    that isn’t defined elsewhere/previously, a crash will occur. The log for the run will show the name of the undefined substitution on a line like this:

    KeyError: 'margie'

  • If you create a FISH function signature with only one part (FLT instead of f:FLT), you’ll get a log error in json.jstree like this:

    lastLine = out[-1]

  • If you create a FISH function signature with spaces in it. Same error as previous. Did my lthing ithing work?

  • If you set up a table or directive that has a :name: that is referenced using :tnum: or :fnum: that is not created in output. This occurs on a markup error. Failure to create will be much likelier with tables, where markup errors cause the entire table to be skipped on doc write. By comparison, the figure directive is harder to fully break. However, if a table or figure so referenced does not appear in output, Sphinx throws an exception on the attempts to link to it from :tnum: or :fnum:.

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. NOTE: We no longer build chm files, but this is left here as a matter of historical record and/or against the possibility that we, however inadvisably, somehow decide to do so again one day.

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.