[Debian-science-sagemath] Math rendering broken in documentation

[E. Madison Bray]

On Sun, Feb 24, 2019 at 3:32 PM Tobias Hansen <thansen at debian.org> wrote:
>
> Hi,
>
> I just applied the last changes to the sphinx 1.8 patch that should have fixed math rendering in the documentation. It didn't fix it. Turns out that it doesn't work since sagemath 8.2-1, when we switched to sphinx 1.7. MathJax.js is not present in the "_static" folders in the documentation anymore since then. I'm not sure how it should be. Should the html files directly reference /usr/share/javascript/mathjax/MathJax.js or should the file be installed with the documentation? I also haven't been able to figure out yet why it is not installed anymore.

I'm not sure why it broke for you, but maybe just to help point you in
the right direction: Because sage's documentation is split up into
quite a large number of "sub-documents", normally with Sphinx each one
of those subdocuments would have its own _static directory.

However, since the contents of those _static directories is
essentially the same for each sub-document, if you have actual full
copies of each of them it adds a pretty enormous size to the full
documentation.

So in the sage_setup.docbuild.ext.mutidocs Sphinx extension there's
kind of a hack (see `def link_static_files`) where it will rmtree
these _static directories and replace them with a symlink to the
corresponding "master document's" _static directory.

So it could be that that extension is not working properly for some reason.

P.S. I've been pretty unhappy for some time with that solution too: It
does not work e.g. on Windows where the browser doesn't understand
symlinks, so for the Windows version of Sage I get rid even of the
symlinks and just rewrite the HTML sources with the proper relative
paths to files in _static.  Personally I would prefer that that were
the solution used in the first place by the Sphinx builder for
sub-documents, but I haven't looked into how to do it yet.