Documentation temporary notes for the move to readthedocs

To make maintenance and contributions easier, we're taking the docs out of the main repo.

Current test:

• MathJax Docs repo -- github.com/pkra/mathjax-docs
• Experimental 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. But we decided that it makes sense to separate them)

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

Readthedocs has a nice standard theme that offers better features than ours (including version). However, the theme does not allow enough customization (e.g. breadcrumbs to www.mathjax.org). Since we will switch the main website to a twitter-bootstrap look, Peter looked into bootstrap-based sphinx themes.

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 add a "edit on github" link to each documentation page. We also have a "version warning".

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

Since the sphinx-bootstrap theme has to be customized anyway, this isn't as big a problem as it would be with the main theme. Also, sphinx-bootstrap has a lot of nice features and is being maintained more actively.

Using advice from stackoverflow, we will keep the entire editing history in the new repository.

TODO:

• add readme and license to the mathjax-docs repo & push to MathJax/mathjax-docs
• switch themes on mathjax-docs to the sphinx-bootstrap theme with Peter's modification (Peter should fork the sphinx-bootstrap theme and make the modifications there)
• redirect the old docs to the new docs, i.e., mathjax.org/docs to docs.mathjax.org/en/