Skip to content

Documentation temporary notes for the move to readthedocs

pkra edited this page Aug 1, 2012 · 8 revisions

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.

Clone this wiki locally