GammaLib

Any clues how to package the needed things in GammaLib?

• Download a local copy of Mathjax: http://www.mathjax.org/download/
• Tell Sphinx to use the local copy of Mathjax: http://sphinx-doc.org/latest/ext/math.html#confval-mathjax_path
• Tell Doxygen to use the local copy of Mathjax: http://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_mathjax_relpath

• How should the download be done? Add a separate make download-mathjax target? Use curl or wget or Python to do the download?
• When should the download be done? Automatically with make doc because fast local docs is what most developers want?
• For the online docs and users that don’t want to download Mathjax, the Sphinx and Doxygen docs still need to point to the Mathjax version on the web, so the use of local Mathjax needs to be optional somehow.

IPython has a script to download Mathjax that we could maybe adapt if you want to use Python for the download:
http://ipython.org/ipython-doc/stable/install/install.html#mathjax
https://github.com/ipython/ipython/blob/master/IPython/external/mathjax.py

Shark adds some JavaScript lines in the Sphinx and Doxygen header to optionally load the local or online version of Mathjax:
http://image.diku.dk/shark/sphinx_pages/build/html/rest_sources/tutorials/for_developers/managing_the_documentation.html#mathjax
https://github.com/chrisvana/shark_copy/blob/master/doc/doxygen_pages/templates/header.html
https://github.com/chrisvana/shark_copy/blob/master/doc/sphinx_pages/templates/layout.html#L6

I think this is a nice solution, although I think the default should be to use a local version if available so that it’s fast and no web request is made if the local version is available.

I won’t have time to implement and test this before the coding sprint, if someone else wants to do it, please go ahead.

The only problem I see with the download during making is that you’ll miss the download in case that the machine is not connected to internet during installation. So ideally, the stuff should be shipped with GammaLib.

We may not do this for developers (they could use indeed a specific target to download the fonts), but when building the release packages we should just add the fonts to the package before building the tarball.

On the other hand, I see that MathJax-2.3 comprises 32.9 MB of data, which I would prefer not having within gammalib (this would make the tarball very large). So we may use the download during make, but eventually alert the user when the download did not work.