Enable MathJax in the TOC of Sage reference manual and documentation website #29993

kwankyu · 2020-06-26T07:48:33Z

We do that. The trick is to add :math: role somewhere. Try to find it :-)

We also reorganize the TOC a bit while we are at it. In particular,

the plane and space curves section is split away from elliptic and hyperelliptic curves section.

CC: @slel @jhpalmieri

Component: documentation

Author: Kwankyu Lee

Branch/Commit: 6c881bc

Reviewer: John Palmieri

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

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

kwankyu · 2020-06-26T07:49:27Z

Branch: u/klee/29993

sagetrac-git · 2020-06-26T07:51:14Z

Commit: 18acfd2

sagetrac-git · 2020-06-26T07:51:14Z

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

`18acfd2`	`Enable MathJax in TOC page`

sagetrac-git · 2020-06-26T07:55:01Z

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

`939308c`	`Enable MathJax in TOC page`

sagetrac-git · 2020-06-26T07:55:01Z

Changed commit from 18acfd2 to 939308c

kwankyu · 2020-06-26T07:58:14Z

Author: Kwankyu Lee

sagetrac-git · 2020-06-30T06:23:29Z

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

`49e32da`	`Enable MathJax in TOC page`

sagetrac-git · 2020-06-30T06:23:29Z

Changed commit from 939308c to 49e32da

sagetrac-git · 2020-07-09T07:14:15Z

Changed commit from 49e32da to 3e266ab

sagetrac-git · 2020-07-09T07:14:15Z

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

`3e266ab`	`Enable MathJax in TOC page`

sagetrac-git · 2020-07-29T05:29:35Z

Changed commit from 3e266ab to 6e64dd8

sagetrac-git · 2020-07-29T05:29:35Z

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

`6e64dd8`	`Enable MathJax in TOC page`

jhpalmieri · 2020-08-11T03:46:10Z

comment:11

Fails to merge.

sagetrac-git · 2020-08-11T08:17:45Z

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

`032df6c`	`Enable MathJax in TOC page`

sagetrac-git · 2020-08-11T08:17:45Z

Changed commit from 6e64dd8 to 032df6c

davidlowryduda · 2020-08-11T20:39:04Z

comment:16

Is there a reason why we want to enable mathjax on the TOC? Maybe the idea is that perhaps we have been omitting putting tex in the TOC before for some reason, and now we can? Or is there perhaps a particular reason?

jhpalmieri · 2020-08-11T23:21:21Z

comment:17

It looks okay to me. I don't understand the changes in the themes; can you explain those?

kwankyu · 2020-08-16T07:06:56Z

comment:18

Replying to @davidlowryduda:

Is there a reason why we want to enable mathjax on the TOC? Maybe the idea is that perhaps we have been omitting putting tex in the TOC before for some reason, and now we can? Or is there perhaps a particular reason?

There have been maths in the TOC, like p-adic and SL_2(Z). I guess they were not in tex just because mathjax didn't work. This ticket solves the problem.

kwankyu · 2020-08-20T09:51:39Z

comment:25

Replying to @kwankyu:

The pdf doc of the TOC does not still render the maths correctly with this ticket. That might be one of the reasons.

This is fixed now, by somewhat ad-hoc manner.

Along the way, I also resurrected the Sage reference manual website for pdfs, which has been broken (I might be guilty for this).

jhpalmieri · 2020-08-20T17:54:16Z

comment:26

Would you mind changing :math:`e^\pi+1=0` to :math:`e^{i\pi}+1=0`? And I think I would call the line \(s=\frac{1}{2}+it\) just a "line", not an "imaginary line".

kwankyu · 2020-08-21T00:51:37Z

comment:27

Replying to @jhpalmieri:

Would you mind changing :math:`e^\pi+1=0` to :math:`e^{i\pi}+1=0`?

Of course, not. Thank you.

And I think I would call the line \(s=\frac{1}{2}+it\) just a "line", not an "imaginary line".

Okay.

kwankyu · 2020-08-21T01:02:53Z

comment:28

To check the documentation website for pdf docs, run:

sage --docbuild reference pdf
sage --docbuild website html

and open local/share/doc/sage/html/en/index.html.

Running

sage --docbuild website pdf

generates a not-so-useful file local/share/doc/sage/pdf/en/website/sage_documentation.pdf.

sagetrac-git · 2020-08-21T01:03:11Z

Changed commit from 5976182 to 1f116f9

sagetrac-git · 2020-08-21T01:03:11Z

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

`1f116f9`	`Fixes for reviewer comments`

sagetrac-git · 2020-08-21T01:12:01Z

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

`6c881bc`	`Fixes missed in the previous commit`

sagetrac-git · 2020-08-21T01:12:01Z

Changed commit from 1f116f9 to 6c881bc

jhpalmieri · 2020-08-21T03:49:51Z

comment:32

The html version looks good, but I'm having problems with the PDF. You should be able to run sage --docbuild all pdf to have it build the html website file and everything else in PDF format.

Broken before this ticket: in local/share/doc/sage/html/en/index.html, there are supposed to be PDF icons next to each document, as links leading to the PDF builds. Those are missing, because the file _static/pdf.png is missing. For some reason, it is not copied from src/doc/en/website/static to local/share/doc/sage/html/en/_static.
If I copy that file by hand, then the links are available, but the one for the reference manual (local/share/doc/sage/pdf/en/reference/index.html) is badly formatted. It is an html file with links to the different components in PDF format, but the table of contents basically appear twice, once badly and then once better, but not perfect.
mathjax is not enabled in that main reference manual html file.

kwankyu · 2020-08-21T04:21:08Z

comment:33

Replying to @jhpalmieri:

The html version looks good, but I'm having problems with the PDF. You should be able to run sage --docbuild all pdf to have it build the html website file and everything else in PDF format.

Broken before this ticket: in local/share/doc/sage/html/en/index.html, there are supposed to be PDF icons next to each document, as links leading to the PDF builds. Those are missing, because the file _static/pdf.png is missing. For some reason, it is not copied from src/doc/en/website/static to local/share/doc/sage/html/en/_static.

Did you run sage --docbuild website html? This copies the PDF icon.

If I copy that file by hand, then the links are available, but the one for the reference manual (local/share/doc/sage/pdf/en/reference/index.html) is badly formatted. It is an html file with links to the different components in PDF format, but the table of contents basically appear twice, once badly and then once better, but not perfect.

I think you are seeing the old version.

jhpalmieri · 2020-08-21T04:45:20Z

comment:34

Replying to @kwankyu:

Replying to @jhpalmieri:

The html version looks good, but I'm having problems with the PDF. You should be able to run sage --docbuild all pdf to have it build the html website file and everything else in PDF format.

Broken before this ticket: in local/share/doc/sage/html/en/index.html, there are supposed to be PDF icons next to each document, as links leading to the PDF builds. Those are missing, because the file _static/pdf.png is missing. For some reason, it is not copied from src/doc/en/website/static to local/share/doc/sage/html/en/_static.

Did you run sage --docbuild website html? This copies the PDF icon.

This works, but it should not be necessary: I ran both sage --docbuild all html and sage --docbuild all pdf, and at least one of those should build the website page. See line 582 in src/sage_setup/docbuild/__init__.py:

            if format == 'pdf':
                # First build the website page. This only takes a few seconds.
                getattr(get_builder('website'), 'html')()

If I copy that file by hand, then the links are available, but the one for the reference manual (local/share/doc/sage/pdf/en/reference/index.html) is badly formatted. It is an html file with links to the different components in PDF format, but the table of contents basically appear twice, once badly and then once better, but not perfect.

I think you are seeing the old version.

The version I see has (for example) the new sentences "Welcome to the Sage reference manual. Here you find documentation for all of Sage <http://www.sagemath.org/>_'s features, illustrated with lots of examples. A thematic index follows." So it's the new one. (I also ran make doc-clean before building the documentation.) I'm attaching local/share/doc/sage/pdf/en/reference/index.html.

kwankyu · 2020-08-21T05:23:32Z

comment:35

Attachment: index.html.gz

Replying to @jhpalmieri:

Replying to @kwankyu:

Replying to @jhpalmieri:

The html version looks good, but I'm having problems with the PDF. You should be able to run sage --docbuild all pdf to have it build the html website file and everything else in PDF format.

Broken before this ticket: in local/share/doc/sage/html/en/index.html, there are supposed to be PDF icons next to each document, as links leading to the PDF builds. Those are missing, because the file _static/pdf.png is missing. For some reason, it is not copied from src/doc/en/website/static to local/share/doc/sage/html/en/_static.

Did you run sage --docbuild website html? This copies the PDF icon.

This works, but it should not be necessary: I ran both sage --docbuild all html and sage --docbuild all pdf, and at least one of those should build the website page. See line 582 in src/sage_setup/docbuild/__init__.py:
            if format == 'pdf':
                # First build the website page. This only takes a few seconds.
                getattr(get_builder('website'), 'html')()

Strangely sage --docbuild all html does not copy the PDF icon, but ``sage --docbuild website html` does. I don't know why. I didn't touch this part.

I think you are seeing the old version.

The version I see has (for example) the new sentences "Welcome to the Sage reference manual. Here you find documentation for all of Sage <http://www.sagemath.org/>_'s features, illustrated with lots of examples. A thematic index follows." So it's the new one. (I also ran make doc-clean before building the documentation.) I'm attaching local/share/doc/sage/pdf/en/reference/index.html.

Right. It is strange. The file local/share/doc/sage/pdf/en/reference/index.html is generated using the file local/share/doc/sage/html/en/website/index.html as a template. Would you upload this file as well so that I can compare it with mine?

kwankyu · 2020-08-21T05:51:12Z

comment:36

Replying to @kwankyu:

Strangely sage --docbuild all html does not copy the PDF icon, but ``sage --docbuild website html` does.

I withdraw this assertion. It is quite confusing...

kwankyu · 2020-08-21T06:39:16Z

Attachment: index.2.html.gz

local/share/doc/sage/pdf/en/reference/index.html

kwankyu · 2020-08-21T06:40:19Z

comment:37

I added the file local/share/doc/sage/pdf/en/reference/index.html, the right one.

kwankyu · 2020-08-21T07:25:11Z

comment:38

I don't know why, but would you try specifically?

sage --docbuild reference pdf

kwankyu · 2020-08-21T14:21:37Z

comment:39

Replying to @jhpalmieri:

I ran both sage --docbuild all html and sage --docbuild all pdf, and at least one of those should build the website page.

I now see what have happened to you. You did not run make build, but only ran make doc-clean, sage --docbuild all html and sage --docbuild all pdf. Right? Thus you built the new document by old docbuild code.

Please try again. This time you run make; sage --docbuild all pdf.

Still the PDF icon would not appear. This problem existed before this ticket, I think. Anyway, this copies the PDF icon to the right place:

$ sage --docbuild website html
[website  ] building [html]: targets for 1 source files that are out of date
[website  ] Merging environment/index files...
[website  ] ... done (0 todos, 1 index, 0 citations, 0 modules)
[website  ] Merging js index files...
[website  ] ... done (15 js index entries)
[website  ] copying static files... ... done
[website  ] dumping search index in English (code: en)... done
[website  ] The HTML pages are in local/share/doc/sage/html/en/website.
Build finished. The built documents can be found in .../local/share/doc/sage/html/en/website

Notice that "copying static files...". Then reload local/share/doc/sage/html/en/index.html.

kwankyu · 2020-08-21T14:45:40Z

comment:40

To see clearly the problem of the PDF icon:

Running make doc-clean; sage --docbuild all html does not install the PDF icon to the right place, that is under local/share/doc/sage/html/en/website/_static.

Running make doc-clean; sage --docbuild website html does install the PDF icon to the right place, that is under local/share/doc/sage/html/en/website/_static.

jhpalmieri · 2020-08-21T16:51:46Z

comment:41

Replying to @kwankyu:

Replying to @jhpalmieri:

I ran both sage --docbuild all html and sage --docbuild all pdf, and at least one of those should build the website page.

I now see what have happened to you. You did not run make build, but only ran make doc-clean, sage --docbuild all html and sage --docbuild all pdf. Right? Thus you built the new document by old docbuild code.

Please try again. This time you run make; sage --docbuild all pdf.

You're right, this fixed it.

Still the PDF icon would not appear. This problem existed before this ticket, I think.

Right, that's what I said in comment:32. It would be nice to fix that, too.

kwankyu · 2020-08-21T22:33:04Z

comment:42

Replying to @jhpalmieri:

Still the PDF icon would not appear. This problem existed before this ticket, I think.

Right, that's what I said in comment:32. It would be nice to fix that, too.

I would love to see it fixed. But I have no idea of how to fix it. Do you have?

I suggest to fix it separately, and not to delay this ticket.

kwankyu · 2020-08-22T00:47:02Z

comment:43

I created a ticket for the PDF icon problem: #30418.

jhpalmieri · 2020-08-22T20:12:56Z

Reviewer: John Palmieri

jhpalmieri · 2020-08-22T20:12:56Z

comment:44

Okay, let's merge it.

vbraun · 2020-08-26T21:15:44Z

Changed branch from u/klee/29993 to 6c881bc

kwankyu added this to the sage-9.2 milestone Jun 26, 2020

kwankyu added c: documentation labels Jun 26, 2020

This comment has been minimized.

Sign in to view

kwankyu added the s: needs review label Jun 26, 2020

This comment has been minimized.

Sign in to view

jhpalmieri added s: needs work and removed s: needs review labels Aug 11, 2020

kwankyu added s: needs review and removed s: needs work labels Aug 11, 2020

This comment has been minimized.

Sign in to view

kwankyu changed the title ~~Enable MathJax in the TOC of Sage reference manual and Sage documentation site~~ Enable MathJax in the TOC of Sage reference manual and documentation website Aug 21, 2020

jhpalmieri added s: positive review and removed s: needs review labels Aug 22, 2020

vbraun removed the s: positive review label Aug 26, 2020

vbraun closed this as completed in dad33be Aug 26, 2020

kwankyu mentioned this issue Nov 7, 2020

Missing PDF icons in the Sage documentation website #30418

Closed

Enable MathJax in the TOC of Sage reference manual and documentation website #29993

Enable MathJax in the TOC of Sage reference manual and documentation website #29993

Comments

kwankyu commented Jun 26, 2020

kwankyu commented Jun 26, 2020

sagetrac-git mannequin commented Jun 26, 2020

sagetrac-git mannequin commented Jun 26, 2020

sagetrac-git mannequin commented Jun 26, 2020

sagetrac-git mannequin commented Jun 26, 2020

This comment has been minimized.

kwankyu commented Jun 26, 2020

This comment has been minimized.

sagetrac-git mannequin commented Jun 30, 2020

sagetrac-git mannequin commented Jun 30, 2020

sagetrac-git mannequin commented Jul 9, 2020

sagetrac-git mannequin commented Jul 9, 2020

sagetrac-git mannequin commented Jul 29, 2020

sagetrac-git mannequin commented Jul 29, 2020

jhpalmieri commented Aug 11, 2020

sagetrac-git mannequin commented Aug 11, 2020

sagetrac-git mannequin commented Aug 11, 2020

This comment has been minimized.

davidlowryduda commented Aug 11, 2020

jhpalmieri commented Aug 11, 2020

kwankyu commented Aug 16, 2020

kwankyu commented Aug 20, 2020

jhpalmieri commented Aug 20, 2020

kwankyu commented Aug 21, 2020

kwankyu commented Aug 21, 2020

sagetrac-git mannequin commented Aug 21, 2020

sagetrac-git mannequin commented Aug 21, 2020

sagetrac-git mannequin commented Aug 21, 2020

sagetrac-git mannequin commented Aug 21, 2020

jhpalmieri commented Aug 21, 2020

kwankyu commented Aug 21, 2020

jhpalmieri commented Aug 21, 2020

kwankyu commented Aug 21, 2020

kwankyu commented Aug 21, 2020

kwankyu commented Aug 21, 2020

kwankyu commented Aug 21, 2020

kwankyu commented Aug 21, 2020

kwankyu commented Aug 21, 2020

kwankyu commented Aug 21, 2020

jhpalmieri commented Aug 21, 2020

kwankyu commented Aug 21, 2020

kwankyu commented Aug 22, 2020

jhpalmieri commented Aug 22, 2020

jhpalmieri commented Aug 22, 2020

vbraun commented Aug 26, 2020