Generating yade documentation
===============================

1. Get sphinx 1.0 (development snapshots are fine) either from 

* packages at https://launchpad.net/~yade-users/+archive/external
** sudo apt-add-repository ppa:yade-users/external; sudo apt-get update; sudo apt-get install python-sphinx python-bibtex

* from its repository:

** hg clone http://bitbucket.org/birkenfeld/sphinx/
** optionally apply the patch (only avoids warnings) from
     http://bitbucket.org/birkenfeld/sphinx/issue/407/patch-do-not-inspect-boost-python-functions
** run 
     python setup.py install

2. Python default encoding must be set to utf-8. As it is not the default, PYTHONPATH=. is used to make Python import local sitecustomize.py file at startup which changes this setting. (The value cannot be set after startup, from within the script)

3. Run (from the current directory, replacing PREFIX by the yade install path)

	PYTHONPATH=. yade yadeSphinx.py [optional outDir; _build by default]

It will be create/update $outDir/{html,latex}. The latex file (Yade.tex) is to be processed with xelatex (rather than latex). See README.latex for details.

====

ipython_console_highlighting.py is copied from matplotlib's trunk/matplotlib/lib/matplotlib/sphinxext


Generating yade documentation as a book (for the official chapter references)
=============================================================================

First run yadeSphinx.py as explained above. It will generate modules documentation and other things that we use for generating the book.
Second run yadeBookSphinx.py (same command as above, adding 'Book' in the script name)

