Opened 10 years ago

Last modified 7 years ago

#13143 closed enhancement

Use MathJax by default when building docs from Makefile — at Version 14

Reported by: jhpalmieri Owned by: GeorgSWeber
Priority: minor Milestone: sage-5.5
Component: build Keywords: Makefile doc MathJax sd40
Cc: nthiery Merged in:
Authors: John Palmieri Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: #9774, #13121, #6495 Stopgaps:

Status badges

Description (last modified by jhpalmieri)

At the moment, running make runs make doc, which in turn runs make doc-html. This runs Sphinx without the -j option, so MathJax (or jsMath, pre #9774) is not used: png image files are used instead. Using png images is much slower, so we should use MathJax (or jsMath) by default.

Timing and disk space information:

Tutorial without MathJax:

$ rm -rf devel/sage/doc/output
$ time sage --docbuild tutorial html
...
real	2m17.950s
user	1m29.441s
sys	0m15.478s
$ du -s -h devel/sage/doc/output
3.9M	output/

With MathJax:

$ rm -rf devel/sage/doc/output
$ time sage --docbuild tutorial html -j
...
real	0m9.871s
user	0m6.530s
sys	0m1.739s
$ du -s -h devel/sage/doc/output
 8.5M	output/

When building all of the documentation, the disk space actually drops, going from about 320M (without MathJax) to about 295M (with).


This has #6495 as a dependency, although that isn't necessary. The Sage library patch here could easily be rebased to avoid that dependency.

Change History (15)

Changed 10 years ago by jhpalmieri

root repo

comment:1 Changed 10 years ago by jhpalmieri

  • Status changed from new to needs_review

comment:2 Changed 10 years ago by jhpalmieri

  • Description modified (diff)

comment:3 Changed 10 years ago by jhpalmieri

  • Description modified (diff)

comment:4 Changed 10 years ago by kcrisman

Here's a question. I've noticed that sometimes looking at MathJax stuff when I'm not on the internet is less than great. What is the story then?

But this certainly looks right.

Maybe something should then also be added to the developer or installation guide (wherever the make options are documented other than in the Makefile) that points out how not to use MathJax in a build. Like to do make build doc-html or whatever the correct syntax would be.

comment:5 Changed 10 years ago by jhpalmieri

  • Cc nthiery added
  • Description modified (diff)

comment:6 Changed 10 years ago by jhpalmieri

The "v2" patches do the following:

  • turn MathJax on by default, by modifying the script sage-env and by modifying how the variable's value is checked in the doc building files
  • pass the "no-pdf-links" option only when building the website document, so its presence (or lack) on the command-line doesn't cause the reference manual to be rebuilt.

comment:7 Changed 10 years ago by jhpalmieri

In response to Karl-Dieter's comment, I've added some documentation, to the "environment variables" section of the installation guide.

comment:8 Changed 10 years ago by kcrisman

Ok, this is more minimalist than I would like (i.e., have all the make targets documented somewhere) but I think it's appropriate for this ticket. I'm sorry that I don't have time to give this full review, though again it seems ok.

comment:9 Changed 10 years ago by jhpalmieri

See #13219 for documentation of the make targets.

comment:10 Changed 10 years ago by jhpalmieri

  • Dependencies changed from #9774 to #9774, #13121

comment:11 Changed 10 years ago by jhpalmieri

  • Keywords sd40 added

comment:12 Changed 10 years ago by drkirkby

I had a problem with Latex creating thousands of errors on CentOS 4.7 (an old version of Linux, which I need to run for some commercial software). See discussion at:

http://groups.google.com/forum/?fromgroups#!topic/sage-devel/7erAQRbHYUU

At John Palmieri's suggestion, I run:

$ rm -rf SAGE_ROOT/devel/sage/doc/output
$ sage --docbuild all html -j

and the documentation built OK, with no errors.

Dave

comment:13 Changed 10 years ago by jhpalmieri

  • Dependencies changed from #9774, #13121 to #9774, #13121, #6495

comment:14 Changed 10 years ago by jhpalmieri

  • Description modified (diff)
Note: See TracTickets for help on using tickets.