Skip to content

Documentation update process

Jump to bottom
pkra edited this page Oct 8, 2012 · 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) with one important difference: we add new branches only upon the next release, i.e., master corresponds to latest and there is no separate branch for the latest version.

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

  1. This is part of the Release process checklist.
  2. Clone the repository git clone https://github.com/mathjax/mathjax-docs.git
  3. Create a branch corresponding to the current version, i.e., the version that will be replaced by the new release.
  4. In that "current" branch, modify
    • 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>
  5. Commit & push pack to github: git commit -a -m "(log message about the 'current' branch)" && git push origin (current branch)
  6. Checkout the master branch,
    • update the version number in the Sphinx configuration file config.py.
  7. Commit & push pack to github: git commit -a -m "(log message about version change)" && git push origin master

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

MathJax Wiki

Clone this wiki locally