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 DONE
• 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) DONE
• redirect the old docs to the new docs, i.e., mathjax.org/docs to docs.mathjax.org/en/

Next issue: rtfd currently uses an outdated jquery which breaks the search.

Let's use github-pages in the mean time. And here's a build-script of sorts which will generate the entire docs. Run it, and then check the produced html, and then push it back to github.

#/bin/bash
cd /tmp
git clone https://github.com/mathjax/mathjax-docs.git
cd mathjax-docs
for remote in `git branch -r | grep -v master `; do git checkout --track $remote ; done
git checkout v1.0
sphinx-build . temp/en/v1.0/
git checkout v1.1-latest
sphinx-build . temp/en/v1.1-latest/
git checkout v2.0-latest
sphinx-build . temp/en/v2.0-latest/
git checkout master
sphinx-build . temp/en/latest/
git checkout gh-pages
rm -Rf "en/"
mv "temp/en" .
rmdir "temp"
rm -rf "en/latest/.doctrees"
rm -rf "en/v2.0-latest/.doctrees"
rm -rf "en/v1.1-latest/.doctrees"
rm -rf "en/v1.0/.doctrees"
rm -rf "en/latest/.buildinfo"
rm -rf "en/v2.0-latest/.buildinfo"
rm -rf "en/v1.1-latest/.buildinfo"
rm -rf "en/v1.0/.buildinfo"

gh-pages branch can be accessed via http://mathjax.github.com/mathjax-docs/en/latest/

That's more than we do right now, but not as much as the rtfd-badge gives... Will look if I can copy their design...