Enforce MathJax for every page of Sage documentation

[kwankyu]

HTML pages of our documentation that contain maths only in TOC trees do not render maths by MathJax because Sphinx does not include MathJax javascript files as the Sphinx MathJax extension does not recognize maths in TOC trees and to save loading time. See for instance,

https://doc.sagemath.org/html/en/reference/schemes/index.html

There could be several solutions:

1. Fix in the upstream Sphinx MathJax extension. A relevant discussion is

   There is no way to enforce MathJax when maths only appear in TOC trees. sphinx-doc/sphinx#10192

2. Add dummy :math:... to every inflicted pages to enable MathJax.

3. Enable MathJax by brute force by adding line

html_js_files = ['MathJax.js?config=TeX-AMS_HTML-full', 'mathjax_sage.js']

for conf files. But this results in duplicate MathJax inclusion
in the generated html file.

4. Rewrite maths in titles using bold, italics, superscripts, and subscripts as allowed in rst format.

A good solution would be implemented in this ticket.

Component: documentation

Author: John Palmieri

Branch/Commit: 231b0e0

Reviewer: Kwankyu Lee

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

[jhpalmieri]

comment:2

I don't know much about html. What is the disadvantage to duplicate MathJax inclusion in html files?

[jhpalmieri]

comment:3

We could also adopt a style that strongly discourages math from titles, and we could replace (for example) `p`-adic by <em>p</em>-adic. Html can handle boldface, italics, subscripts, and superscripts, and that probably covers almost all of our math usage in tables of contents.

[kwankyu]

comment:4

Replying to @jhpalmieri:

I don't know much about html. What is the disadvantage to duplicate MathJax inclusion in html files?

Perhaps the same disadvantage of running a program twice, aside aesthetic reason.

[kwankyu]

comment:5

Replying to @jhpalmieri:

We could also adopt a style that strongly discourages math from titles, and we could replace (for example) `p`-adic by <em>p</em>-adic. Html can handle boldface, italics, subscripts, and superscripts, and that probably covers almost all of our math usage in tables of contents.

Doc files are in reStructuredText format. HTML tags do not work in rst files, as I understand.

If Sphinx people do not help, then we may go for the option (2) somehow.

[jhpalmieri]

comment:6

Replying to @kwankyu:

Replying to @jhpalmieri:

I don't know much about html. What is the disadvantage to duplicate MathJax inclusion in html files?

Perhaps the same disadvantage of running a program twice, aside aesthetic reason.

The web page https://developer.yahoo.com/performance/rules.html claims that duplicate inclusion of javascript files hurts performance.

[jhpalmieri]

comment:7

Replying to @kwankyu:

Replying to @jhpalmieri:

We could also adopt a style that strongly discourages math from titles, and we could replace (for example) `p`-adic by <em>p</em>-adic. Html can handle boldface, italics, subscripts, and superscripts, and that probably covers almost all of our math usage in tables of contents.

Doc files are in reStructuredText format.

No kidding.

HTML tags do not work in rst files, as I understand.

rst can also do bold, italics, superscripts, and subscripts.

[kwankyu]

comment:8

Replying to @jhpalmieri:

HTML tags do not work in rst files, as I understand.

rst can also do bold, italics, superscripts, and subscripts.

Okay, then.

[jhpalmieri]

comment:9

How would you like to proceed? Should we start converting math in module titles to bold, italics, etc.?

[kwankyu]

comment:10

Replying to @jhpalmieri:

How would you like to proceed? Should we start converting math in module titles to bold, italics, etc.?

I would like to go for the option 1 or 2. If Sphinx people do not provide an official way to enforce MathJax inclusion, then we may investigate unofficial ways (such as tweaking Shinx's MathDomain somehow, where has_equation test is defined). If we fail, then a simplest (but a bit ugly) solution is the option 2 (adding dummy math nodes).

I really don't like the option 4, which would make our documentation include maths in an alternative format.

Anyway I am busy now for my main work. Let me get back to this ticket later.

[kwankyu]

comment:11

For the option 2, this dummy works pretty well:

--- a/src/doc/en/reference/finite_rings/index.rst
+++ b/src/doc/en/reference/finite_rings/index.rst
@@ -1,5 +1,8 @@
 Finite Rings
-====================================
+============
+
+.. math::
+   :nowrap:
 
 Finite Rings
 ------------

Getting maths back by adding this bit of ugly thing seems worth it.

[jhpalmieri]

comment:12

This single change works, since footer.txt is imported into the various index files:

diff --git a/src/doc/en/reference/footer.txt b/src/doc/en/reference/footer.txt
index fa7bc30eea..e9b5166be4 100644
--- a/src/doc/en/reference/footer.txt
+++ b/src/doc/en/reference/footer.txt
@@ -1,6 +1,9 @@
 Indices and Tables
 ==================
 
+.. math::
+   :nowrap:
+
 * `Index <../genindex.html>`_
 * `Module Index <../py-modindex.html>`_
 * `Search Page <../search.html>`_

[jhpalmieri]

comment:13

I can push a branch with that change (+ some minor fixes for the TOC entries for the p-adics page) if you want.

[kwankyu]

comment:14

Replying to @jhpalmieri:

I can push a branch with that change (+ some minor fixes for the TOC entries for the p-adics page) if you want.

Please go ahead. Thank you.

[kwankyu]

comment:15

Moreover we may need to add somewhere in the developer manual a remark about the purpose of the added lines to prevent anyone from deleting the seemingly useless lines.

[kwankyu]

comment:16

Replying to @jhpalmieri:

This single change works, since footer.txt is imported into the various index files.

Good idea!

[jhpalmieri]

Branch: u/jhpalmieri/sphinx-force-mathjax

[jhpalmieri]

Commit: f57953a

[jhpalmieri]

comment:18

Okay, here is a branch. Before this, about half of the p-adic TOC entries used `p`-adic and the rest used p-adic (no math mode); now they all use the former.

---

New commits:

f57953a

trac 33347: force MathJax on every reference manual index page

[jhpalmieri]

Author: John Palmieri

[kwankyu]

comment:20

As in

https://en.wikipedia.org/wiki/P-adic_analysis

p-adic seems in a better style than p-Adic in titles. If you agree, I can upload a commit to apply this style to p-adics.

[slel]

comment:21

Replying to @kwankyu:

As in

https://en.wikipedia.org/wiki/P-adic_analysis

p-adic seems in a better style than p-Adic in titles.

+1.

Good main title "p-adic analysis" there,
subsection title "P-adic quantum mechanics" needs work:

• https://en.wikipedia.org/wiki/P-adic_analysis#P-adic_quantum_mechanics

though the main title "p-adic_quantum_mechanics"
at the dedicated page for it is good:

• https://en.wikipedia.org/wiki/P-adic_quantum_mechanics

[kwankyu]

New commits:

963b355

Better p-adic than p-Adic

[kwankyu]

Changed commit from f57953a to 963b355

[kwankyu]

Changed branch from u/jhpalmieri/sphinx-force-mathjax to public/33347

[kwankyu]

Reviewer: Kwankyu Lee

[kwankyu]

comment:23

I am positive on the branch. But let me do the final check on the built documentation.

[sagetrac-git]

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

231b0e0

trac 33347: doctest fix

[sagetrac-git]

Changed commit from 963b355 to 231b0e0

[jhpalmieri]

comment:25

One easy-to-fix doctest failure, otherwise looks good to me.

For a future ticket: if we can think of a way to solve it, changing the html title of the web page to not use math would be nice. As it is, the title bar in my browser says Ring \(\ZZ/n\ZZ\) of integers modulo \(n\) — Finite Rings. Is there a handy way to autoconvert the title?

[kwankyu]

comment:26

Replying to @jhpalmieri:

For a future ticket: if we can think of a way to solve it, changing the html title of the web page to not use math would be nice. As it is, the title bar in my browser says Ring \(\ZZ/n\ZZ\) of integers modulo \(n\) — Finite Rings. Is there a handy way to autoconvert the title?

Simply removing \(, \) pairs, backslashes, (and $ perhaps) would be enough. This could be done on the fly by javascript...

[kwankyu]

comment:27

Morally greenbot.

[kwankyu]

comment:28

Replying to @kwankyu:

Simply removing \(, \) pairs, backslashes, (and $ perhaps) would be enough. This could be done on the fly by javascript...

Done in #33475.

[vbraun]

Changed branch from public/33347 to 231b0e0