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

[Tobias Hansen]

On 2/25/19 2:09 PM, E. Madison Bray wrote:
> 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.

Thanks for the explanation. The symlinks are there, just MathJax.js is not.

Best, Tobias