Configure mathjax in sphinx config and upgrade to Mathjax v3 #33600

tobiasdiez · 2022-03-30T12:43:48Z

Configure mathjax in sphinx config, and not in a javascript file. In this way, we can get ride of the custom theme option mathjax_macros, which is not understood by other themes. This is preparation to support the furo theme, see #33601.

We also upgrade Mathjax to v3. The configs were migrated using
https://mathjax.github.io/MathJax-demos-web/convert-configuration/convert-configuration.html
with the following manual changes:

Remove processEscapes since this now defaults to true in v3 anyway.
Remove ignoreHtmlClass/processHtmlClass since they are set to the default values.
Remove noerrors extension, which hides error messages. Normally, there shouldn't be any errors and, if there are, its probably good to have them displayed very prominently so that reviewers can discover these issues. But I don't feel very strongly about this change. Reference: https://docs.mathjax.org/en/latest/input/tex/extensions/noerrors.html

Refs #25833

Depends on #25833

CC: @kwankyu @strogdon @haraldschilly @mkoeppe

Component: documentation

Branch/Commit: public/docs/mathjax_ext @ 89ec417

Reviewer: Kwankyu Lee

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

The text was updated successfully, but these errors were encountered:

tobiasdiez · 2022-03-30T13:46:25Z

comment:2

This seems to do the job for me. With the disclaimer that I could only test the tutorial and dev guide, since "reference" fails with a lot of errors on gitpod. Among them

[tensor_fr] Extension error (matplotlib.sphinxext.plot_directive):
[tensor_fr] Handler <function _copy_css_file at 0x7f47e225b4c0> for event 'build-finished' threw an exception (exception: [Errno 17] File exists: '/home/gitpod/sage-local/share/doc/sage/html/en/reference/tensor_free_modules/_static')

sagetrac-git · 2022-03-30T13:46:58Z

Branch pushed to git repo; I updated commit sha1. New commits:

`9bc4432`	`Migrate rest of config`

sagetrac-git · 2022-03-30T13:46:58Z

Changed commit from b90316d to 9bc4432

mkoeppe · 2022-03-30T16:30:53Z

comment:4

See #30296 and references within for previous efforts / discussion regarding mathjax 3

tobiasdiez · 2022-03-30T18:41:18Z

comment:5

Thanks for the pointer. It seems the issues discussed in that ticket revolve around packaging problems. I circumvent these here by using the CDN.

mkoeppe · 2022-03-30T23:31:32Z

comment:6

I would expect that people want to keep an offline version without using the CDN.

mkoeppe · 2022-03-31T01:33:07Z

comment:7

Replying to @tobiasdiez:

It seems the issues discussed in that ticket revolve around packaging problems.

One of the "references within" is #25833 for the upgrade to 3.x.
It would be important to know whether #25833 comment:9 is still current, and whether it is relevant for our use of Sphinx.

kwankyu · 2022-03-31T05:03:59Z

comment:8

Replying to @mkoeppe:

One of the "references within" is #25833 for the upgrade to 3.x.
It would be important to know whether #25833 comment:9 is still current, and whether it is relevant for our use of Sphinx.

That feature (not compatible with latex) of mathjax2 would be relevant only in online use of mathjax, such as in jupyter notebook.

As far as I know, that "automatic line breaking" is not used in our documentation. If there is any, then that is something to be fixed.

For us, there is no reason not to upgrade to mathjax3.

kwankyu · 2022-03-31T05:14:43Z

comment:9

Sage cell has moved to mathjax3 (relatively) long time ago. It may be worth while to check the mathjax3 configuration used in sage cell:

https://github.com/sagemath/sagecell/blob/master/js/cell.js

kwankyu · 2022-03-31T05:25:04Z

comment:10

You converted single quotes to double quotes. Single quotes are conventionally used for strings containing code (not plain English). You should not change them without compelling reasons.

tobiasdiez · 2022-03-31T08:34:45Z

comment:11

Replying to @kwankyu:

Replying to @mkoeppe:

One of the "references within" is #25833 for the upgrade to 3.x.
It would be important to know whether #25833 comment:9 is still current, and whether it is relevant for our use of Sphinx.

That feature (not compatible with latex) of mathjax2 would be relevant only in online use of mathjax, such as in jupyter notebook.

As far as I know, that "automatic line breaking" is not used in our documentation. If there is any, then that is something to be fixed.

For us, there is no reason not to upgrade to mathjax3.

Thanks for the clarification!

tobiasdiez · 2022-03-31T08:37:17Z

comment:12

Replying to @kwankyu:

You converted single quotes to double quotes. Single quotes are conventionally used for strings containing code (not plain English). You should not change them without compelling reasons.

I wasn't aware that such a styleguide rule exists. The existing code in both files doesn't seem to follow it either - it's just a random mix of single and double quotes. I tried to make at least the lines homogeneous that I've touched.

kwankyu · 2022-03-31T10:56:00Z

comment:13

Replying to @tobiasdiez:

Replying to @kwankyu:

You converted single quotes to double quotes. Single quotes are conventionally used for strings containing code (not plain English). You should not change them without compelling reasons.

I wasn't aware that such a style guide rule exists.

I must say it's not a rule. But single quotes are commonly used for code strings.

The existing code in both files doesn't seem to follow it either - it's just a random mix of single and double quotes. I tried to make at least the lines homogeneous that I've touched.

Leaving single-quoted strings as they are will contribute overall homogeneity of the sage code base.

sagetrac-git · 2022-03-31T11:53:28Z

Branch pushed to git repo; I updated commit sha1. New commits:

`e4e1118`	`Convert double quotes to single quotes`

sagetrac-git · 2022-03-31T11:53:28Z

Changed commit from 9bc4432 to e4e1118

tobiasdiez · 2022-03-31T11:56:00Z

comment:15

Replying to @kwankyu:

Leaving single-quoted strings as they are will contribute overall homogeneity of the sage code base.

Sadly there is not much of a homogeneity. For example, latex-macros.py contains

    args = "("
    for x in sample_args:
        count += 1
        args += str(x) + ','
    args += ')'

Anyway, I've reverted these changes.

kwankyu · 2022-03-31T12:58:40Z

comment:16

Replying to @tobiasdiez:

Sadly there is not much of a homogeneity. For example, latex-macros.py contains

    args = "("
    for x in sample_args:
        count += 1
        args += str(x) + ','
    args += ')'

Well.. that is embarrassing.

Anyway, I've reverted these changes.

Thank you.

sagetrac-git · 2022-04-07T08:08:21Z

Changed commit from 7cc5eb7 to c92b6c0

tobiasdiez · 2022-04-07T16:01:57Z

comment:40

Replying to @kwankyu:

Now the branch at #25833 is merged.

Presently the default is offline mathjax3, to experiment. When everything is okay, we should decide what should be the default.

Thanks for your work on this!

sagetrac-git · 2022-04-08T01:19:06Z

Changed commit from c92b6c0 to 5412dcb

sagetrac-git · 2022-04-08T01:19:06Z

Branch pushed to git repo; I updated commit sha1. New commits:

`46d0d69`	`Add sage package mathjax3`
`6da197e`	`Remove garbage files`
`bd60742`	`Put into mathjax subdirectory`
`5b47d22`	`Fix checksums`
`f1cdce2`	`Merge branch 'spkg-mathjax3-trac25833'`
`5412dcb`	`Rename config variable to --use-cdns`

kwankyu · 2022-04-08T01:24:31Z

comment:42

I think that offline sage documentation should be the default as it has been. So I renamed the config variable to --use-cdns. If we change the default to "online" in the future, then we can just turn on --use-cdns.

sagetrac-git · 2022-04-08T01:35:41Z

Branch pushed to git repo; I updated commit sha1. New commits:

`2a186d2`	`Fix a typo`

sagetrac-git · 2022-04-08T01:35:41Z

Changed commit from 5412dcb to 2a186d2

kwankyu · 2022-04-08T02:43:17Z

comment:44

To build doc with mathjax cdn, we only need

diff --git a/src/doc/Makefile b/src/doc/Makefile
index 90bea5dfac..82134ea3b4 100644
--- a/src/doc/Makefile
+++ b/src/doc/Makefile
@@ -21,7 +21,7 @@ doc-inventory--%:
 
 # Matches doc-html--developer, doc-html--reference-manifolds etc.
 doc-html--%:
-       cd $(SAGE_ROOT) && ./sage --docbuild --no-pdf-links $(subst -,/,$(subst doc-html--,,$@)) html $(SAGE_DOCBUILD_OPTS)
+       cd $(SAGE_ROOT) && ./sage --docbuild --use-cdns --no-pdf-links $(subst -,/,$(subst doc-html--,,$@)) html $(SAGE_DOCBUILD_OPTS)
 
 # reference manual, inventory
 ifndef SAGE_ROOT

So ./configure --online-doc would do the above.

antonio-rojas · 2022-04-08T06:06:52Z

comment:45

Any reason os.path.join(SAGE_SHARE, 'mathjax3') is hardcoded in docs/conf.py instead of using the MATHJAX_DIR defined in env.py?

sagetrac-git · 2022-04-08T06:12:06Z

Changed commit from 2a186d2 to c42ec23

sagetrac-git · 2022-04-08T06:12:06Z

Branch pushed to git repo; I updated commit sha1. New commits:

`c42ec23`	`Use MATHJAX_DIR`

kwankyu · 2022-04-08T06:12:47Z

comment:47

Replying to @antonio-rojas:

Any reason os.path.join(SAGE_SHARE, 'mathjax3') is hardcoded in docs/conf.py instead of using the MATHJAX_DIR defined in env.py?

No. You are right. Thanks.

sagetrac-git · 2022-04-08T12:51:27Z

Changed commit from c42ec23 to 89ec417

sagetrac-git · 2022-04-08T12:51:27Z

Branch pushed to git repo; I updated commit sha1. New commits:

`8df9661`	`Upgrade mathjax package to mathjax3`
`43b802d`	`Merge branch 'spkg-mathjax3-trac25833'`
`89ec417`	`Fix MATHJAX_DIR env variable`

tobiasdiez · 2022-04-08T18:31:28Z

comment:49

Should we merge this ticket with #25833, since you replace the mathjax 2 package there, so one probably should upgrade the config in one go as well. What do you think?

tobiasdiez · 2022-04-08T19:29:22Z

comment:50

Replying to @kwankyu:

I think that offline sage documentation should be the default as it has been. So I renamed the config variable to --use-cdns. If we change the default to "online" in the future, then we can just turn on --use-cdns.

I'm not sure what should be the default for developers (but I guess everyone has internet if they contribute to trac...so I guess cdn would make sense), but the server should use the cdn to increase the speed or not? Comparing the loading times from the cdn vs sage's server, the cdn is a factor 10 quicker (13 ms vs 140ms).

kwankyu · 2022-04-08T23:42:02Z

comment:51

Replying to @tobiasdiez:

Should we merge this ticket with #25833, since you replace the mathjax 2 package there, so one probably should upgrade the config in one go as well. What do you think?

I agree. Let's do it. I will upload the branch of this ticket to #25833.

kwankyu · 2022-04-08T23:49:25Z

comment:52

Replying to @tobiasdiez:

Replying to @kwankyu:

I think that offline sage documentation should be the default as it has been. So I renamed the config variable to --use-cdns. If we change the default to "online" in the future, then we can just turn on --use-cdns.

I'm not sure what should be the default for developers (but I guess everyone has internet if they contribute to trac...so I guess cdn would make sense), but the server should use the cdn to increase the speed or not? Comparing the loading times from the cdn vs sage's server, the cdn is a factor 10 quicker (13 ms vs 140ms).

The default is aimed at sage users with lowest resources.

I think we need to provide ./configure --online-doc option so that everyone can choose what he/she wants. Developers would of course have internet resource usually, but sometimes not (on airplane :). Personally I would prefer offline-doc.

kwankyu · 2022-04-09T11:41:53Z

comment:54

Replying to @kwankyu:

I think we need to provide ./configure --online-doc option so that everyone can choose what he/she wants.

No. We already have SAGE_DOCBUILD_OPTS environment variable. So we can

export SAGE_DOCBUILD_OPTS="--use-cdns"

before make.

kwankyu · 2022-04-09T23:46:45Z

Changed author from Tobias Diez, Kwankyu Lee to none

kwankyu · 2022-04-09T23:46:45Z

Reviewer: Kwankyu Lee

kwankyu · 2022-04-09T23:46:45Z

comment:56

Replying to @tobiasdiez:

https://doc.sagemath.org/html/en/developer/trac.html#reviewing-and-closing-tickets

Okay. Let's close this.

tobiasdiez added this to the sage-9.6 milestone Mar 30, 2022

tobiasdiez added c: documentation labels Mar 30, 2022

This comment has been minimized.

Sign in to view

tobiasdiez changed the title ~~Configure mathjax in sphinx config public/docs/mathjax_ext~~ Configure mathjax in sphinx config and upgrade to Mathjax v3 Mar 30, 2022

tobiasdiez added the s: needs review label Mar 30, 2022

mkoeppe added s: needs info and removed s: needs review labels Mar 31, 2022

tobiasdiez added s: needs review and removed s: needs info labels Mar 31, 2022

kwankyu removed the s: needs review label Apr 5, 2022

kwankyu added s: needs work and removed s: needs review labels Apr 8, 2022

tobiasdiez removed this from the sage-9.6 milestone Apr 9, 2022

tobiasdiez added s: positive review and removed s: needs work labels Apr 9, 2022

mkoeppe removed the s: positive review label May 11, 2022

mkoeppe closed this as completed May 11, 2022

slel mentioned this issue May 31, 2022

Upgrade to MathJax 3 and configure Sage #25833

Closed

Configure mathjax in sphinx config and upgrade to Mathjax v3 #33600

Configure mathjax in sphinx config and upgrade to Mathjax v3 #33600

Comments

tobiasdiez commented Mar 30, 2022

This comment has been minimized.

This comment has been minimized.

tobiasdiez commented Mar 30, 2022

sagetrac-git mannequin commented Mar 30, 2022

sagetrac-git mannequin commented Mar 30, 2022

mkoeppe commented Mar 30, 2022

tobiasdiez commented Mar 30, 2022

mkoeppe commented Mar 30, 2022

mkoeppe commented Mar 31, 2022

kwankyu commented Mar 31, 2022

kwankyu commented Mar 31, 2022

kwankyu commented Mar 31, 2022

tobiasdiez commented Mar 31, 2022

tobiasdiez commented Mar 31, 2022

kwankyu commented Mar 31, 2022

sagetrac-git mannequin commented Mar 31, 2022

sagetrac-git mannequin commented Mar 31, 2022

tobiasdiez commented Mar 31, 2022

kwankyu commented Mar 31, 2022

sagetrac-git mannequin commented Apr 7, 2022

tobiasdiez commented Apr 7, 2022

sagetrac-git mannequin commented Apr 8, 2022

sagetrac-git mannequin commented Apr 8, 2022

kwankyu commented Apr 8, 2022

sagetrac-git mannequin commented Apr 8, 2022

sagetrac-git mannequin commented Apr 8, 2022

kwankyu commented Apr 8, 2022

antonio-rojas commented Apr 8, 2022

sagetrac-git mannequin commented Apr 8, 2022

sagetrac-git mannequin commented Apr 8, 2022

kwankyu commented Apr 8, 2022

sagetrac-git mannequin commented Apr 8, 2022

sagetrac-git mannequin commented Apr 8, 2022

tobiasdiez commented Apr 8, 2022

tobiasdiez commented Apr 8, 2022

kwankyu commented Apr 8, 2022

kwankyu commented Apr 8, 2022

kwankyu commented Apr 9, 2022

kwankyu commented Apr 9, 2022

kwankyu commented Apr 9, 2022

kwankyu commented Apr 9, 2022