System package information and spkg-configure for mathjax

[mkoeppe]

After #31035, our mathjax spkg is only used in our sphinx documentation. We currently ship a "stripped" version of mathjax 2.7.4 (see build/pkgs/mathjax/spkg-src; #25032, #18596); #25833 proposes an upgrade to 3.x.

We add an spkg-configure.m4 script for the standard package mathjax, as well as corresponding system package information in build/pkgs/mathjax/distros/ using https://repology.org/projects/?search=mathjax

---

Random references:

py-mathjax/pypi/py-mathjax at master · kiwi0fruit/py-mathjax
https://github.com/kiwi0fruit/py-mathjax/tree/master/pypi/py-mathjax

Debian JavaScript Maintainers / mathjax · GitLab
https://salsa.debian.org/js-team/mathjax

sphinx/setup.py at 3.x · sphinx-doc/sphinx
https://github.com/sphinx-doc/sphinx/blob/3.x/setup.py

Math support for HTML outputs in Sphinx — Sphinx 4.0.0+ documentation
https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax

sphinx-ext-mathjax - Google Search
https://www.google.com/search?safe=off&sxsrf=ALeKk03spVlQ9ALPLJJCbNfF9EIdC_LYuQ%3A1596929073175&ei=MTQvX8mUCuKU0PEPu-yOiAE&q=sphinx-ext-mathjax&oq=sphinx-ext-mathjax&gs_lcp=CgZwc3ktYWIQAzIFCAAQzQIyBQgAEM0CMggIABDNAhCLAzIICAAQzQIQiwMyCAgAEM0CEIsDOgQIABBHOgcIIxCwAhAnOgcIIRAKEKABOgUIIRCgAToFCCEQqwJQmyhY4UVgtFBoAHABeACAAWqIAeUHkgEDOS4ymAEAoAEBqgEHZ3dzLXdpergBA8ABAQ&sclient=psy-ab&ved=0ahUKEwiJ8Yyx4IzrAhViCjQIHTu2AxEQ4dUDCAw&uact=5

Math support for HTML outputs in Sphinx — Sphinx 4.0.0+ documentation
https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax

sphinx/mathjax.py at 3.x · sphinx-doc/sphinx
https://github.com/sphinx-doc/sphinx/blob/3.x/sphinx/ext/mathjax.py

CC: @jcamp0x2a @paulmasson @slel @egourgoulhon @orlitzky @kwankyu @jhpalmieri @nthiery @enriqueartal @kiwifb @antonio-rojas @tobihan @Etn40ff @tobiasdiez

Component: packages: standard

Keywords: mathjax, sd111

Author: Samuel Lelièvre, ...

Branch/Commit: public/30296 @ 5c624ab

Issue created by migration from https://trac.sagemath.org/ticket/30296

[mkoeppe]

comment:2

There are numerous unresolved tickets regarding mathjax...

• System package information and spkg-configure for mathjax #30296
• Allow LaTeX in text3d #30226
• Prevent JSmol from phoning home #30030
• #29993 comment:9
• Remove hardcoded mathjax path in docs/conf.py #28547
• MathJax causing unusual hanging in large notebooks #28257
• Remove bad mathjax symlink and bad mathjax directories #26612
• Upgrade to MathJax 3 and configure Sage #25833
• Meta-ticket: Update other packages to using the sage-dist-helpers functions + DESTDIR where applicable #24024
• Confusing documentation on MathJax in light of use in Jupyter notebook #24367
• Improve introspection capabilities of Sage Jupyter Kernel #25015
• In the built documentation, replace duplicate files by symlinks #25111
• MathJax javascript loaded more than once #22394
• Don't strip MathJax fonts #18596

[mkoeppe]

comment:4

For availability of mathjax in distributions, see https://repology.org/project/mathjax/versions

[mkoeppe]

Branch: u/mkoeppe/system_package_information_and_spkg_configure_for_mathjax

[mkoeppe]

comment:6

The commit only indicates where the system directory should be inserted.

I don't plan to work on this ticket.

Hoping that people knowledgeable about the Jupyter notebook and/or documentation building will be interesting in working on it.

---

New commits:

68a0dda

build/pkgs/sage_conf/src/sage_conf.py.in: Add MATHJAX_DIR

[mkoeppe]

Commit: 68a0dda

[mkoeppe]

comment:7

There is also a pip-installable package https://pypi.org/project/py-mathjax/, but I think using it has not benefits for us.

[mkoeppe]

comment:8

Also notebook bundles mathjax ... why do we install another copy?

[jhpalmieri]

comment:10

Replying to @mkoeppe:

Also notebook bundles mathjax ... why do we install another copy?

The change

diff --git a/build/make/Makefile.in b/build/make/Makefile.in
index ed5294cc4e..3d65767bf7 100644
--- a/build/make/Makefile.in
+++ b/build/make/Makefile.in
@@ -289,7 +289,7 @@ base: $(inst_patch) $(inst_pkgconf)
 # produce plots.
 DOC_DEPENDENCIES = sagelib $(inst_sphinx) \
        | $(SAGERUNTIME) $(inst_maxima) $(inst_networkx) $(inst_scipy) $(inst_sympy) \
-       $(inst_matplotlib) $(inst_pillow) $(inst_mathjax) $(inst_mpmath) \
+       $(inst_matplotlib) $(inst_pillow) $(inst_mpmath) \
        $(inst_ipykernel) $(inst_jupyter_client) $(inst_conway_polynomials) \
        $(inst_tachyon) $(inst_jmol) $(inst_thebe) $(inst_ipywidgets)
 
diff --git a/build/pkgs/mathjax/type b/build/pkgs/mathjax/type
index a6a7b9cd72..134d9bc32d 100644
--- a/build/pkgs/mathjax/type
+++ b/build/pkgs/mathjax/type
@@ -1 +1 @@
-standard
+optional

avoids building mathjax, but then Sphinx doesn't find it when building the documentation. So if we want to use the version bundled with notebook, we need to make sure that Sphinx knows where to find it.

[mkoeppe]

comment:11

src/sage/docs/conf.py expects sage.env.MATHJAX_DIR to be set to the location. This is what we'd have to configure if we take mathjax either from a system installation, or some other source.

[mkoeppe]

Changed commit from 68a0dda to none

[mkoeppe]

Changed branch from u/mkoeppe/system_package_information_and_spkg_configure_for_mathjax to none

[slel]

Changed keywords from none to mathjax

[slel]

comment:16

Replying to @mkoeppe:

Also notebook bundles mathjax ... why do we install another copy?

See

• Stack Overflow question 28909747: How do I configure mathjax for iPython notebooks?

and the various answers there, including

• StackOverflow answer 58866858

which states

Jupyter ships with its own (smaller) version of MathJax.
This is why it is not able to find the (Computer Modern)
'TeX' font -- there only is the STIX font.

So it's possible that the smaller version of MathJax
shipped by Jupyter Notebook is not enough for our Sphinx use.

Configuring Jupyter Notebook to use Sage's fuller MathJax
might have benefits (ability to typeset more math?)
and/or drawbacks (performance?).

[mkoeppe]

comment:17

Replying to @slel:

Configuring Jupyter Notebook to use Sage's fuller MathJax
might have benefits (ability to typeset more math?)

This should be investigated.

[mkoeppe]

Changed keywords from mathjax to mathjax, sd111

[kwankyu]

comment:41

Replying to @antonio-rojas:

Well, my point is that once there is just one copy of _static, then maybe it's not that bad to just copy over the entire contents of the system mathjax dir.

One copy to html/_static might suffice.

Other question: the location of the system mathjax is /usr/share/mathjax on all linux platforms? Or does it vary?

[kwankyu]

comment:42

The mathjax3 tarball is around 5Mb. I think this is not so big. Then is it worth while to detect the system mathjax and copy it instead of downloading the tarball?

[antonio-rojas]

comment:43

Replying to @kwankyu:

Other question: the location of the system mathjax is /usr/share/mathjax on all linux platforms? Or does it vary?

mathjax doesn't provide an install script, so unfortunately there's no standard location and it's up to each distro to decide where to install it. On Arch we use /usr/share/mathjax, other distros may use mathjax3 instead if they also ship v2. (But, according to https://repology.org/project/mathjax/versions, no other distro is shipping mathjax 3 yet)

[kwankyu]

comment:44

Replying to @antonio-rojas:

Replying to @kwankyu:

Other question: the location of the system mathjax is /usr/share/mathjax on all linux platforms? Or does it vary?

mathjax doesn't provide an install script, so unfortunately there's no standard location and it's up to each distro to decide where to install it.

mathjax is a javascript library, and perhaps unique in that among sage spkgs. I doubt if spkg-configure.m4 script is relevant with mathjax.

@matthias: would you comment?

[mkoeppe]

comment:45

Given that the spread of mathjax 3 in distributions is so low, I don't think that there is a need to support system packages providing it. If this changes in the future, spkg-configure.m4 would be the correct mechanism though.

[orlitzky]

comment:46

Replying to @kwankyu:

mathjax is a javascript library, and perhaps unique in that among sage spkgs. I doubt if spkg-configure.m4 script is relevant with mathjax.

It is kind of an awkward fit, since there's no reliable way of detecting via spkg-configure.m4 where the the html/js files might live. But we can at the very least check a list of known locations. The gp2c package does that for lack of a better strategy.

[mkoeppe]

comment:47

One would probably only want to search for the system library when also system node is installed, which would give discoverability.

[kwankyu]

comment:48

Replying to @orlitzky:

Replying to @kwankyu:

mathjax is a javascript library, and perhaps unique in that among sage spkgs. I doubt if spkg-configure.m4 script is relevant with mathjax.

It is kind of an awkward fit, since there's no reliable way of detecting via spkg-configure.m4 where the the html/js files might live. But we can at the very least check a list of known locations. The gp2c package does that for lack of a better strategy.

I agree. Still as this mathjax package is not big and does not take time to install, I doubt if it would ever be worth while to put necessary efforts for this package.

Hence I suggest closing this ticket as "won't fix".

[orlitzky]

comment:49

Replying to @kwankyu:

Hence I suggest closing this ticket as "won't fix".

Sage's mathjax has "never" worked for me. This is probably due to font stripping (#18596 comment:4), but undoing that would make the package larger.

So I'd quite like the ability to use the unbroken copy my distro provides, regardless of any time/bandwidth savings. Ultimately I can write the spkg-configure if no one else does it. I'll probably wait until the mathjax-3.x upgrade is done though.

[kwankyu]

comment:50

Replying to @orlitzky:

Replying to @kwankyu:

Hence I suggest closing this ticket as "won't fix".

Sage's mathjax has "never" worked for me. This is probably due to font stripping (#18596 comment:4), but undoing that would make the package larger.

So I'd quite like the ability to use the unbroken copy my distro provides, regardless of any time/bandwidth savings. Ultimately I can write the spkg-configure if no one else does it. I'll probably wait until the mathjax-3.x upgrade is done though.

Okay. Thanks. Does mathjax3 (#25833) work for you?

[orlitzky]

comment:51

Replying to @kwankyu:

Okay. Thanks. Does mathjax3 (#25833) work for you?

Yes, thanks, replied there.

[kwankyu]

comment:53

Replying to Michael Orlitzky:

Ultimately I can write the spkg-configure if no one else does it. I'll probably wait until the mathjax-3.x upgrade is done though.

Now that mathjax3 is well in place, would you do the work?

From Matthias: src/sage/docs/conf.py expects sage.env.MATHJAX_DIR to be set to the location. This is what we'd have to configure if we take mathjax either from a system installation, or some other source.

[orlitzky]

comment:54

Replying to Kwankyu Lee:

Replying to Michael Orlitzky:

Ultimately I can write the spkg-configure if no one else does it. I'll probably wait until the mathjax-3.x upgrade is done though.

Now that mathjax3 is well in place, would you do the work?

Now I'm waiting for my distro package to be upgraded (https://bugs.gentoo.org/837722), but yes, I'll get to it eventually.

[mkoeppe]

On the question of the many copies of mathjax in _static, see #35538 (comment)

[mkoeppe]

On conda, the mathjax package installs into lib/mathjax/es5/ (https://github.com/conda-forge/mathjax-feedstock/blob/main/recipe/mathjax-path)

[kwankyu]

@orlitzky is working on this issue. Unfortunately there is a problem with no easy fix in using system mathjax without incurring a regression in using spkg mathjax. (In my view, many systems mathjax are installed in a way not working nicely with Sphinx but conda and our spkg are doing it right).

I still have doubts on the benefits of using system mathjax. We need mathjax only for our documentation. I think the documentation should use mathjax CDN in the first place, but for users without internet, we provide spkg mathjax. The spkg is small and takes no time in installing as it is just a bunch of javascript and data files. Then why do we make efforts to use system mathjax? Of course, I would not ask this if there was no regression in using system mathjax.

If there's a convincing argument, then I would accept the regression (which is only about organization not about functioning),

@orlitzky found a good solution.

[kwankyu]

#36098 just got positive review. I am not sure if that may close this issue.

[orlitzky]

I used a Closes: tag in one my commits that should close the issue automatically when it is merged: https://github.blog/2013-01-22-closing-issues-via-commit-messages/