-
-
Notifications
You must be signed in to change notification settings - Fork 1.2k
Documentation temporary notes for the move to readthedocs
To make maintenance and contributions easier, we're considering taking the docs out of the main repo and encourage contributions better.
Current test: mathjax-docs.readthedocs.org or github.com/pkra/mathjax-docs
Readthedocs is a service that automatically builds Sphinx documentation (as HTML, pdf and epub). Github offers a webhook so that readthedocs builds the documentation whenever a change occurs in the repository. (Note: We don't have to separate the docs to use readthedocs, it can find the docs in the main repo.)
Readthedocs has a nice standard theme that offers better features than ours (including version).
The idea is to host the docs at docs.mathjax.org. Accordingly, we need to offer users a clear way back to www.mathjax.org
Since we host the docs on github, there's the additional advantage of editing the files in githubs webinterface (wich creates a fork and pull request).
Thanks to the support on the readthedocs issue tracker (https://github.com/rtfd/readthedocs.org/issues/226), we can make use of this and add a "edit on github" link to each documentation page. We still need a "version warning" (see https://github.com/rtfd/readthedocs.org/issues/220). But we're probably loosing the SEO on the docs when switching to docs.mathjax.org which might reduce the problem...
The bad thing: the url for these "edit on github" links has to be (partially) hard coded in _templates
-- for each version of the docs (see also the issue 226 there). It's a small price to pay right now, but if we get to localization of our docs we might want to revisit this.