Skip to content

Documentation update process

Jump to bottom
Peter Krautzberger edited this page Sep 1, 2016 · 21 revisions

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

How does it work?

The github repository contains the sphinx source. The compiled copy at <docs.mathjax.org> is provided through the awesome services of ReadTheDocs, i.e., docs.mathjax.org is a CNAME for mathjax.rtfd.org. RTD 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 review it and ReadTheDocs will build it automatically. Easy as that.

(For creating new pages, you can use the GitHub interface as well.)

Release process checklist -- GitHub version

(Almost all of this can be done via the GitHub UI.)

  1. This is part of the Release process checklist. The first few items could be done before the beta launch. We're working within the main docs repo.
  2. Make a pull request to merge master back into the branch current, the branch corresponding to the version that will be replaced by the new release. This compensates for any updates made to master (since we usually won't fix current)
  3. Create a branch from master named vN.m-latest. (Enter vN.m-latest in the "switch branches" menu and choose "create brach")
  4. Log into ReadTheDocs and add the vN.m-latest branch to the build list.
  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. Upon a non-beta release, merge vN.m-latest back into master.
  7. Check if docs.mathjax.org has successfully built vN.m-latest and master at docs.mathjax.org

Release process checklist -- git version

  1. This is part of the Release process checklist. The first few items could be done before the beta launch.
  2. Clone the repository git clone https://github.com/mathjax/mathjax-docs.git
  3. Merge master into the branch current corresponding to the current version, i.e., the version that will be replaced by the new release.
  4. Push current to github: git commit -a -m "(log message about the 'current' branch)" && git push origin "current"
  5. Create a branch of master corresponding to the released version vN.m-latest and push it to github git push origin vN.m-latest.
  6. Log into ReadTheDocs and add the vN.m-latest branch to the build list.
  7. 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.
  8. When the new documentation is finished, merge vN.m-latest back into master and make a pull request to the main repo.
  9. Check if docs.mathjax.org has successfully built vN.m-latest and master at docs.mathjax.org

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

MathJax Wiki

Clone this wiki locally