Skip to content

Documentation temporary notes for the move to readthedocs

Jump to bottom
pkra edited this page Sep 26, 2012 · 8 revisions

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

Current test:

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

More notes.

So github is out of the race again for the temporary solution (i.e., until readthedocs upgrades their jquery). Simple reason: can't remap the DNS as we need to (b/c the mathjax.github.com is to become the main website's hosting point in the not-so-far future)

Way around it: use cloud files. Now that it's set up, this shouldn't be much work to maintain. Just use cyberduck to update what the above script produces.

It was a bit of a pain to set it up to though, so here are the notes for that -- the rackspace docs aren't perfect, so I used this blog post, but even that misses one point. Anyway: to quote here the crucial paragraphs.

You need to send a POST message to your Storage-Url, with the header X-Container-Meta-Web-Index: index.html if your index page is index.html or any other you would prefer. For you to be able to send this message, and for it to be accepted, you first need to authenticate yourself. For the sake of clarity, let start with the complete example of the POST message you need to send, the complete message is (using curl):

curl -X POST -H "X-Container-Meta-Web-Index: index.html" -H "X-Auth-Token: aaaaaaaa-0000-0000-0000-aaaaaaaa" https://storage100.dcw1.clouddrive.com/v1/MossoCloudFS_1234567a-123c-12d1-7cad-a09878abcde3/your_container/ -v

As you can see, you need something to put in X-Auth-Token field [Note from Peter: you also need the Storage URL], to get that value you have issue this other command in your Mac or Linux terminal:

curl -H "X-Auth-User: your-user-name" -H "X-Auth-Key: 0123456789abcdef01234567899d" https://auth.api.rackspacecloud.com/v1.0/ -v

Where:

  • X-Auth-User: Is the username you use to log into your Rackspace account
  • X-Auth-Key: Is your API key.

MathJax Wiki

Clone this wiki locally