|
|
|
> This will need some updating when we switch the documentation to github-pages
|
|
|
|
|
|
|
|
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/. |
|
|
|
\ No newline at end of file |
