#989649 libjs-mathjax: integrate with dh_sphinxdoc

Package:
libjs-mathjax
Source:
mathjax
Submitter:
Drew Parsons
Date:
2021-11-22 23:33:03 UTC
Severity:
normal
#989649#5
Date:
2021-06-09 13:13:47 UTC
From:
To:
dh_sphinxdoc provides aids for automatically updating references to
.js scripts used in docs generated through sphinx.  In particular it
helps maintain privacy policies by removing the need to reference
external websites such as
https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.9/MathJax.js
from documentation.

At the moment mathjax is not integrating into the dh_sphinxdoc
capabilities. This means privacy hacks need to be made manually for
every package that uses math formatting in its rst or md docs.

Can mathjax be introduced to the dh_sphinxdoc system?
#989649#10
Date:
2021-09-25 06:19:26 UTC
From:
To:
Hi,
there is any news on this?
Also pyresample is impacted by this issue.

kind regards
antonio
#989649#15
Date:
2021-09-25 18:53:27 UTC
From:
To:
Hi Drew, Antonio and all!

My recommendation is to add this line to your conf.py (using a patch):

  mathjax_path = 'file:///usr/share/javascript/mathjax/MathJax.js?config=TeX-AMS-MML_HTMLorMML'

This is better than letting Sphinx generate URLs to some CDN and then
replacing them in dh_sphinxdoc. Any code to do automatic replacement is
error-prone, may not always detect the tags correctly, and may break
when something in Sphinx changes.

With this approach you will have correct URLs in tags from the very
beginning.
#989649#20
Date:
2021-09-26 06:28:10 UTC
From:
To:
Dear Dmitry,
what looked strange to me is that previously I was able to build my
packages (pyresample in particular) without problems.
Now I get warnings about privacy breach so I had the impression that
something is moving in the wrong direction.
By the way adding small patch a patch to conf.py is not a problem for
me, so no problem.

kind regards
antonio

On Sat, 25 Sep 2021 21:53:27 +0300 Dmitry Shachnev <mitya57@debian.org> wrote:
#989649#25
Date:
2021-10-04 10:26:35 UTC
From:
To:
It's not always so simple as adding the conf.py patch.

For the example of fenics-dolfinx 0.3.0-3 (in experimental), the
lintian privacy-breach-generic warning complains about

https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

But there is no local tex-mml-chtml.js file to replace it with.
#989649#30
Date:
2021-11-21 12:26:05 UTC
From:
To:
Oh, this is a bug report against libjs-mathjax already ;-)

Best wishes,

   Julian
#989649#35
Date:
2021-11-21 12:24:15 UTC
From:
To:
That shouldn't be a problem; have a look at
/usr/lib/python3/dist-packages/sphinx/ext/mathjax.py
This is where the tex-mml-chtml.js file is referred to, but that is
overridden by the mathjax_path config file variable.

Unfortunately, though, this completely fails to work with Firefox:

http://docs.mathjax.org/en/v2.7-latest/installation.html#firefox-and-local-fonts

MathJax.js tries to load "file:///extensions/MathMenu.js?V=2.7.9" and
similar, and I cannot fathom how to set things up so that the
[MathJax] path becomes "/usr/share/javascript/mathjax" rather than
"".  I also tried putting a symlink to /usr/share/javascript/mathjax
in the documentation directory and setting mathjax_path to there, but
that fails in the same way.

Any suggestions would be most welcome!

I might post a query to the Debian MathJax maintainers to see if they
have any idea.

Best wishes,

   Julian
#989649#40
Date:
2021-11-22 23:31:38 UTC
From:
To:
OK, update on this...

So all you have to do is add:

mathjax_path = 'file:///usr/share/javascript/mathjax/MathJax.js?config=TeX-AMS-MML_HTMLorMML'

to docs/conf.py

The rest of this turns out to be a bug in version 94.0-1 of Debian
Firefox (at least on my machine).  Upgrading to 94.0-2 fixed the
issue, and the Sphinx-generated documentation (with the mathjax_path
patch) now works fine.

Best wishes,

   Julian