Documentation generation guide

Note that the documentation is now automatically generated via ReadTheDocs and hosted on docs.mathjax.org.

This is a simple tutorial for building the sphinx docs included in the MathJax docs folder.

Building the docs for distribution

The docs directory contains a Makefile that you can use to build the documentation in various formats. Just type make (in that directory) to get a list of the options.

To create a distrubution version of the docs, navigate to the MathJax docs folder and type

make html

This will build the docs and generate html files located in docs/html. When a distribution is being prepared, the docs should be rebuilt and committed to the Git repository.

Building the docs for mathjax.org

To create a version of the docs for mathjax.org, use

make html-mathjax-site

The results will be in docs/html-mathjax-site.

If you are doing this on the mathjax.org server, please use the virtualenv docs, already setup with python2.7 and the lastest sphinx. To active the docs env, run

workon docs

If it has been a while since the last build, you might want to try

pip install -U sphinx

to upgrade it (after you are in the docs env).

Find the version of mathjax you want in mathjax_repos/version/ and then

make html-mathjax-site

After you build the mathjax site docs, either copy the docs to /docs via

cp -r .../docs/ *

or symlink the version to a subdirectory of /docs

ln -s .../mathjax_repos/version/docs/build/html/ .../docs/version/

Getting Sphinx

Sphinx requires the python language be installed on your system. If it is not already on your system, get the latest stable release from http://www.python.org (version 2.7 as of this writing).

Once you have python, you way want to use virtualenv and virtualenvwrapper to separate your various python environments. That this is entirely optional, but the process is the following:

If you have easy_install (which should be included with python) or pip (a better python package installation tool that you can get using easy_install), you should be able to run something like

pip install virtualenv virtualenvwrapper

to obtain these two packages. If not, please see http://www.doughellmann.com/projects/virtualenvwrapper/.

Once you have virtualenvwrapper installed, add these lines to your .bashrc (or your system's equivalent):

source /usr/local/bin/virtualenvwrapper.sh
export WORKON_HOME=~/virtualenvs

Note that you can change the WORKON_HOME path to whatever you like, just be sure to create the directory.

Now you can make a virtualenv for the MathJax docs and install sphinx with something like

$ mkvirtualenv mathjax_docs
(mathjax_docs)$ pip install sphinx

If you don't want to worry about environment control, just install sphinx the traditional way from http://sphinx.pocoo.org/.