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