Opened 2 years ago

Closed 2 years ago

#29993 closed enhancement (fixed)

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

Reported by: Kwankyu Lee Owned by:
Priority: minor Milestone: sage-9.2
Component: documentation Keywords:
Cc: Samuel Lelièvre, John Palmieri Merged in:
Authors: Kwankyu Lee Reviewers: John Palmieri
Report Upstream: N/A Work issues:
Branch: 6c881bc (Commits, GitHub, GitLab) Commit: 6c881bc53699c7628bc5a5fd8d681ee96c273231
Dependencies: Stopgaps:

Status badges

Description (last modified by Kwankyu Lee)

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.

Attachments (2)

index.html (22.1 KB) - added by John Palmieri 2 years ago.
index.2.html (14.3 KB) - added by Kwankyu Lee 2 years ago.
local/share/doc/sage/pdf/en/reference/index.html

Download all attachments as: .zip

Change History (47)

comment:1 Changed 2 years ago by Kwankyu Lee

Branch: u/klee/29993

comment:2 Changed 2 years ago by git

Commit: 18acfd22ef02eb181d225cdfc866b76461604cf1

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

18acfd2Enable MathJax in TOC page

comment:3 Changed 2 years ago by git

Commit: 18acfd22ef02eb181d225cdfc866b76461604cf1939308cceb93de2ff1f1bdb7166cbad19581f474

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

939308cEnable MathJax in TOC page

comment:4 Changed 2 years ago by Kwankyu Lee

Authors: Kwankyu Lee
Description: modified (diff)
Status: newneeds_review

comment:5 Changed 2 years ago by Kwankyu Lee

Description: modified (diff)

comment:6 Changed 2 years ago by git

Commit: 939308cceb93de2ff1f1bdb7166cbad19581f47449e32dae2cc5c8bb1c55c05ef2a9d41c0fd4155d

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

49e32daEnable MathJax in TOC page

comment:7 Changed 2 years ago by git

Commit: 49e32dae2cc5c8bb1c55c05ef2a9d41c0fd4155d3e266ab7f0ad339514ec5dbbe831772b02d23d69

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

3e266abEnable MathJax in TOC page

comment:8 Changed 2 years ago by git

Commit: 3e266ab7f0ad339514ec5dbbe831772b02d23d696e64dd8c1b237db68a72fb641bcae90d666494a1

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

6e64dd8Enable MathJax in TOC page

comment:9 Changed 2 years ago by Matthias Köppe

Cc: Samuel Lelièvre added

comment:10 Changed 2 years ago by Matthias Köppe

Cc: John Palmieri added

comment:11 Changed 2 years ago by John Palmieri

Fails to merge.

comment:12 Changed 2 years ago by John Palmieri

Status: needs_reviewneeds_work

comment:13 Changed 2 years ago by git

Commit: 6e64dd8c1b237db68a72fb641bcae90d666494a1032df6c98836aff3f1c2339f208e3c101b0add4d

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

032df6cEnable MathJax in TOC page

comment:14 Changed 2 years ago by Kwankyu Lee

Status: needs_workneeds_review

comment:15 Changed 2 years ago by Kwankyu Lee

Description: modified (diff)

comment:16 Changed 2 years ago by David Lowry-Duda

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?

comment:17 Changed 2 years ago by John Palmieri

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

comment:18 in reply to:  16 Changed 2 years ago by Kwankyu Lee

Replying to DavidLowry:

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.

comment:19 in reply to:  17 ; Changed 2 years ago by Kwankyu Lee

Replying to jhpalmieri:

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

I split arithmetic geometry (elliptic and hyperelliptic curves) from algebraic geometry (plane and space curves). Other than this, the changes are minor and rephrasings.

If you have better suggestions on the changes, let me know.

comment:20 in reply to:  16 ; Changed 2 years ago by Kwankyu Lee

Status: needs_reviewneeds_work

Replying to DavidLowry:

Maybe the idea is that perhaps we have been omitting putting tex in the TOC before for some reason...

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

comment:21 in reply to:  19 ; Changed 2 years ago by John Palmieri

Replying to klee:

Replying to jhpalmieri:

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

I split arithmetic geometry (elliptic and hyperelliptic curves) from algebraic geometry (plane and space curves). Other than this, the changes are minor and rephrasings.

If you have better suggestions on the changes, let me know.

Sorry, my question was about the changes to the two files layout.html.

comment:22 in reply to:  21 Changed 2 years ago by Kwankyu Lee

Replying to jhpalmieri:

Replying to klee:

Replying to jhpalmieri:

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

I split arithmetic geometry (elliptic and hyperelliptic curves) from algebraic geometry (plane and space curves). Other than this, the changes are minor and rephrasings.

If you have better suggestions on the changes, let me know.

Sorry, my question was about the changes to the two files layout.html.

Ah! They are actually bug fixes. Look at this page:

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

The vertical line, called sidebar toggle, separating the search box on the left and the main content on the right has wrong height and looks ugly.

The changes do the right job to compute the height of the sidebar toggle.

comment:23 Changed 2 years ago by git

Commit: 032df6c98836aff3f1c2339f208e3c101b0add4d59761821124227f84cc639a82b55d747f334b151

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

5976182Enable MathJax in TOC page

comment:24 Changed 2 years ago by Kwankyu Lee

Status: needs_workneeds_review
Summary: Enable MathJax in the TOC of Sage reference manualEnable MathJax in the TOC of Sage reference manual and Sage documentation site

comment:25 in reply to:  20 Changed 2 years ago by Kwankyu Lee

Replying to klee:

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).

comment:26 Changed 2 years ago by John Palmieri

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".

Last edited 2 years ago by John Palmieri (previous) (diff)

comment:27 in reply to:  26 Changed 2 years ago by Kwankyu Lee

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.

comment:28 Changed 2 years ago by Kwankyu Lee

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.

comment:29 Changed 2 years ago by git

Commit: 59761821124227f84cc639a82b55d747f334b1511f116f9f6db3c4540bb9de33af043e0b53859c99

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

1f116f9Fixes for reviewer comments

comment:30 Changed 2 years ago by git

Commit: 1f116f9f6db3c4540bb9de33af043e0b53859c996c881bc53699c7628bc5a5fd8d681ee96c273231

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

6c881bcFixes missed in the previous commit

comment:31 Changed 2 years ago by Kwankyu Lee

Summary: Enable MathJax in the TOC of Sage reference manual and Sage documentation siteEnable MathJax in the TOC of Sage reference manual and documentation website

comment:32 Changed 2 years ago by John Palmieri

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.

comment:33 in reply to:  32 ; Changed 2 years ago by Kwankyu Lee

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.

comment:34 in reply to:  33 ; Changed 2 years ago by John Palmieri

Replying to klee:

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.

Changed 2 years ago by John Palmieri

Attachment: index.html added

comment:35 in reply to:  34 ; Changed 2 years ago by Kwankyu Lee

Replying to jhpalmieri:

Replying to klee:

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?

comment:36 in reply to:  35 Changed 2 years ago by Kwankyu Lee

Replying to klee:

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...

Changed 2 years ago by Kwankyu Lee

Attachment: index.2.html added

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

comment:37 Changed 2 years ago by Kwankyu Lee

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

comment:38 Changed 2 years ago by Kwankyu Lee

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

sage --docbuild reference pdf

comment:39 in reply to:  34 ; Changed 2 years ago by Kwankyu Lee

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.

comment:40 Changed 2 years ago by Kwankyu Lee

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.

comment:41 in reply to:  39 ; Changed 2 years ago by John Palmieri

Replying to klee:

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.

comment:42 in reply to:  41 Changed 2 years ago by Kwankyu Lee

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.

comment:43 Changed 2 years ago by Kwankyu Lee

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

comment:44 Changed 2 years ago by John Palmieri

Reviewers: John Palmieri
Status: needs_reviewpositive_review

Okay, let's merge it.

comment:45 Changed 2 years ago by Volker Braun

Branch: u/klee/299936c881bc53699c7628bc5a5fd8d681ee96c273231
Resolution: fixed
Status: positive_reviewclosed
Note: See TracTickets for help on using tickets.