Documentation update process

The MathJax documentation is written in restructuredText/sphinx-doc and stored in its own GitHub repository, mathjax-docs. We host a compiled copy at http://docs.mathjax.org.

The repository follows the versioning of the main repository (with branches v1.0, v1.1-latest, v2.0-latest etc) with one difference: before a new release, we merge the master branch into the branch for the current release for a final update of that branch.

How does it work?

The repository contains the source.The compiled copy at <docs.mathjax.org> is provided through ReadTheDocs, i.e., docs.mathjax.org is a CNAME for mathjax.rtfd.org. They also provide the documentation as downloads.

ReadTheDocs is a free service sponsored by Python, Mozilla et al to provide automatic compilation of sphinx-doc. A webhook in the settings of a github repository will trigger compilation of the docs whenever the repository changes. ReadTheDocs also provides zipped, PDF and epub versions of each branch. Which branches are compiled can be configured through the ReadTheDocs user account.

Updating the documentation

The easiest way to update a particular page is to visit the respective page at http://docs.mathjax.org and click on the Edit source (on GitHub) link. This takes you to the corresponding blob-view on github where you can simply click Edit (you need to be a logged-in Github user for editing).

When you save your changes version, GitHub automatically creates a fork (if it doesn't exist) and creates a pull request. The MathJax Team will accept or reject it -- and ReadTheDocs will build it automatically. Easy as that.

(For creating new pages, you will still have to clone the repository and submit a pull request.)

Release process checklist

0. This is part of the Release process checklist.
1. Clone the repository git clone https://github.com/mathjax/mathjax-docs.git
2. Merge master into the branch current corresponding to the current version, i.e., the version that will be replaced by the new release.
3. Push current to github: git commit -a -m "(log message about the 'current' branch)" && git push origin "current"
4. Create a branch of master corresponding to the released version vN.m-latest and push it to github git push origin vN.m-latest.
5. Update vN.m-latest with all necessary documentation changes for the new release; in particular
   • update the version number in the Sphinx configuration file config.py.
   • Create a "What's new"-page for the new release.
   • Document all new features.
   • Note: The master branch will always be the one to keep up-to-date, being visible at docs.mathjax.org/en/latest.
6. Merge vN.m-latest back into master.
7. Push vN.m-latest and master back to github. git push origin master vN.m-latest
8. After(!) the release, modify the vN.m-latest branch (Note: this branch will have to be updated updated manually but will allow people to have a stable link for documentation of that version)
   • the edit-on-github link _templates/sourcelink.html to point to the current branch.
   • the theme layout _themes/sphinx-bootstrap/layout.html: add the version-warning to the quick-links:
     • After <li><strong>Quick links</strong></li> insert <li> <a class="btn btn-mini btn-success" href="http://docs.mathjax.org/">Newer version available!</a> </li> (this may seem counter-intuitive, but latest is designed to be more up-to-date.
9. Commit & push pack to github: git commit -a -m "(log message about the new release branch)" && git push origin "vN.m-latest".
10. Commit & push pack to github: git commit -a -m "(log message about version change)" && git push origin master
11. Log into ReadTheDocs and add the vN.m-latest branch to the build list.

Appendix: Understanding the process

Up to MathJax v2.0, the documentation was stored in the main repository. Of course, with git versioning, older branches do contain these older docs.

With MathJax v2.1, we decided to separate the documentation and give it its own repository. That mathjax-docs repository was created by trimming the main repository down to the documentation's source folder. Accordingly, the entire git history of the documentation sources is present in the mathjax-docs repository.

Appendix: Modifying the theme

The current theme is a fork of sphinx-bootstrap by Scotch Media.

If you have to work on the theme, make sure you update all branches! Due to the hack in the theme, you'll have to do this manually for the older branches vs the master branch to take the version-warning-button into account.

Also note: the sourcelink in templates is different for each version since it points to the corresponding branch on github.

Warning There's one difference between the theme in the latest branch and all others: the theme for older branches contains a version warning! Be sure to check that you didn't add the version warning to the branch of the current version and the master branch.

Appendix: a bash script for hosting via github-pages.

In case you ever need it, here's a bash script we used to rebuild the html for multiple versions and hosting through github-pages.

#/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 v2.1-latest
sphinx-build . temp/en/v2.1-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"

Then make sure that everything compiled nicely and commit and push the changes.

git commit -a -m "(log message about changes)" 
git push origin gh-pages

And of course, update the CDN with en/.