Documentation #490
Closed
Documentation #490
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
See https://bitbucket.org/kevindunn/sphinx-extension-mathjax/wiki/Home and https://groups.google.com/forum/#!msg/sphinx-dev/SkLZlqapcM8/tI2qk5uTY3gJ. MathJax renders the LaTeX equations in the browser. This has several advantages: - Compiling the Sphinx docs from scratch is *way* faster, since it doesn't have to compile the LaTeX images. Previously on my machine, it took about half an hour to compile from scratch (mainly due to heavy LaTeX use in the mpmath docs). Now it only takes a couple of minutes. - Because no LaTeX images are stored, the overall size of the compiled docs is smaller. - The rendered math in the browser is selectable (which also means it's searchable), and crisp at arbitrary zoom levels, since it renders the math using actual fonts, not images. So it's just like an equation in a regular LaTeX pdf document. - You can right click on the equation and get a menu that will show the source. As a side benefit, you can also use this to convert the LaTeX to mathml. - No changes are required in the source files. This uses the same :math: pragma as the previous system, so it's very swappable. - This currently uses an online version of the mathjax.js file that is free to use for production, but this can easily be downloaded and used locally for offline use. Disadvantages: - You will not be warned about LaTeX errors at doc compile time. The only way I know to find them is to look at all the rendered html files for yellow MathJax error boxes. Perhaps there is a more streamlined way to do this, though. - There currently are some errors in the GA docs, due to some strange control sequences like \W and \lbrk. I'm not sure where these are defined, but this will have to be fixed if we use this. - Your browser has to render the math at load time, which makes it a little slower for LaTeX intensive pages. Actually, it isn't too bad. And it seems to render from the top down, so you can see the math at the top almost immediately. And while it is rendering, you see the LaTeX source, so you can at least read it. To compare this against the old system, do cd doc make clean # To clear the old docs make html And open a LaTeX intensive page like _build/html/modules/mpmath/functions/hypergeometric.html in your browser and compare it against the current page at docs.sympy.org (in this case, http://docs.sympy.org/0.7.0/modules/mpmath/functions/hypergeometric.html#mpmath.hyp0f1). Note how with the MathJax, you can select parts of the math equations, you can zoom in (using your browser's zoom functionality) without any loss of resolution, and you right click on the equation to get the source.
I previously didn't notice that directory exists for extensions. This is cleaner, and prevents the need to add . to the path in conf.py.
This version seems to be newer. One change I noticed is that bad math now no longer gives a yellow box with an error message, but rather renders what it can with the bad parts in red.
I didn't realize that this extension just converts $math$ into `math`.
This extension converted $math$ to `math` so it would render as LaTeX in Sphinx documents. There were problems with the extension (see issue 2537). I changed all instances of $math$ throughout SymPy to `math`. I also changed some ``math`` in the polys code to `math`, though this is still very inconsistant (I at least tried to be consistant within a file). Note that two backticks (``) causes the text to printed verbatim in a monospace font in Sphinx.
This adds a "source" link next to every function definition in the docs, which shows you to the source of function. The entire source of every file for which at least one function or class is included in the docs is included. See issue 2561.
|
She is here with us at the SciPy sprint, and I had her based her stuff against my mathjax branch, she is working on documentation. The additional commits should go away when we get that in (and I am working on it now, so that should be soon) |
…tchas.txt and guide.txt
|
The changes look good so far. Let's wait for pull #491, since this is based on that. |
|
Awesome patch, thanks! It doesn't seem to apply cleanly anymore, so it needs to be rebased. |
|
I included a rebased version in the 0.7.1 branch. Welcome to SymPy! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.