How to update sphinx documentation:

this_dir=`pwd`
# make easyviz doc with reST format:
cd ../../../lib/scitools
doconce insertdocstr rst .
cd $this_dir

make html
rm ../sphinx/html/*
cp -r _build/html/* ../sphinx-html/

# run easyviz doc with plain again (for pydoc):
cd ../../../lib/scitools
doconce insertdocstr plain .
cd $this_dir

ls _build/html

The statements above are in the script update.sh.


How to generate sphinx documentation:

1. For each module, generate a modulename.txt file:

  :mod:`modulename`
  =======================

  .. automodule:: modulename
     :members:
     :undoc-members:
     :show-inheritance:


2.  Clean up sphinx-genreated files:
rm -rf _build/ _static/ _templates/ conf.py index.txt

3. Let sphinx generate new files:
sphinx-quickstart

Here are some typical answers:
.
n
_
SciTools
H. P. Langtangen, J. Ring, ++
0.7
0.7
.txt
index
n
y
n
n
n
n
y
n
n
y
y
y

(note that we use .txt files, include autodoc and pngmath)

4. Copy list of modules into the autogenerated index.txt file.

5. Edit conf.py to reflect where the scitools source is located:
sys.path.append(os.path.join(os.path.abspath('.'), os.pardir, os.pardir, os.pardir, 'lib', 'scitools'))

5. Run 
make html

6. Load _build/html/index.html into a web browser to see the result

----

The steps above are automated by the generate.sh script. First one may
run make_txt.py to generte new .txt files (this is necessary if there
are new modules being added since last time). Then just run ./generate.sh
to automatically run sphinx tools, edit files, and generate the
documentation.
