Enforce MathJax for every page of Sage documentation
Closed this issue · 35 comments
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:
-
Fix in the upstream Sphinx MathJax extension. A relevant discussion is
-
Add dummy :math:... to every inflicted pages to enable MathJax.
-
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.
- 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
Description changed:
---
+++
@@ -13,8 +13,7 @@
3. Enable MathJax by brute force by adding line
```python
- html_js_files = ['MathJax.js?config=TeX-AMS_HTML-full',
- 'mathjax_sage.js']
+ 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.I don't know much about html. What is the disadvantage to duplicate MathJax inclusion in html files?
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.
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.
Replying to @jhpalmieri:
We could also adopt a style that strongly discourages math from titles, and we could replace (for example)
`p`-adicby<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.
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.
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`-adicby<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.
Description changed:
---
+++
@@ -2,7 +2,7 @@
https://doc.sagemath.org/html/en/reference/schemes/index.html
-There could be several solutions in the order of preference:
+There could be several solutions:
1. Fix in the upstream Sphinx MathJax extension. A relevant discussion is
@@ -18,5 +18,7 @@
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.
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.
How would you like to proceed? Should we start converting math in module titles to bold, italics, etc.?
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.
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.
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>`_I can push a branch with that change (+ some minor fixes for the TOC entries for the p-adics page) if you want.
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.
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.
Replying to @jhpalmieri:
This single change works, since
footer.txtis imported into the various index files.
Good idea!
Commit: f57953a
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 |
Author: John Palmieri
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.
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:
though the main title "p-adic_quantum_mechanics"
at the dedicated page for it is good:
Changed branch from u/jhpalmieri/sphinx-force-mathjax to public/33347
Reviewer: Kwankyu Lee
I am positive on the branch. But let me do the final check on the built documentation.
Branch pushed to git repo; I updated commit sha1. New commits:
231b0e0 | trac 33347: doctest fix |
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?
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...
Morally greenbot.
Changed branch from public/33347 to 231b0e0