Documentation generation guide
Clone this wiki locally
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
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
The results will be in
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
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
After you build the mathjax site docs, either copy the docs to
cp -r .../docs/ *
or symlink the version to a subdirectory of /docs
ln -s .../mathjax_repos/version/docs/build/html/ .../docs/version/
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
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/.