Documentation update process

The MathJax documentation is stored in its own GitHub repository, mathjax-docs and 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). These "main" branches contain the master .rst files of each version. There is an additional orphaned branch, gh-pages, containing a compiled version of the documentation for all versions.

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. Easy as that.

Release process checklist

This assumes you have Sphinx installed (and git, of course).

0. This is part of the Release process checklist so vN.M-latest is assumed to come from there.
1. Clone the repository git clone https://github.com/mathjax/mathjax-docs.git
2. Track all branches, e.g., in bash: for remote in `git branch -r | grep -v master `; do git checkout --track $remote ; done
3. Create the new branch vN.M-latest and tag according to the release process.
4. In the new branch, update the version number in the Sphinx configuration file config.py.
5. Commit & push pack to github: git commit -a -m "(log message about new branch)" && git push origin vN.M-latest
6. Build the HTML for the new branch sphinx-build . vN.M-latest/ (this creates a new folder vN.M-latest).
7. Check out the release before the new release say vA.B-latest.
8. Change the theme of vA.B-latest to add the version warning: modify _theme/sphinx-bootstrap/layout.html (see older branches for the code snippet).
9. Update the sourcelink in _templates to point to the branch (not master).
10. Build the HTML for the branch sphinx-build . vA.B-latest/.
11. Checkout the gh-pages branch: git checkout gh-pages (this will leave the new folders in place).
12. Move the new folders to en/.
13. Replace en/latest with a copy of the vN.M-latest folder.
14. Commit & push pack to github git commit -a -m "(log message about new branch)" && git push origin gh-pages
15. Update the mathjax-docs container on the CDN with en/.
16. Update http://www.mathjax.org/resources/docsindex/.

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.

We also provide downloads via Read The Docs. These are generated automatically whenever a change of the documentation is pushed (there's a webhook in the github repository settings for this).

If Read The Docs updates their jquery, we can host the documentation there directly; this would simplify things further.

Appendix: Modifying the theme

If you have to work on the sphinx-theme (currently sphinx-bootstrap), you should update all branches. Due to the hacks in the theme, you'll have to do this manually for each branch.

Hacks include:

• the sphinx-bootstrap layout.html contains version-warning button -- which is only appropriate for older versions
• the sourcelink in templates is different for each version.

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.

Here's a bash script to rebuild the html for multiple versions.

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