Finding sphinx-build

Sphinx is an excellent tool for generating documentation for projects implemented in Python. Note that after installing Sphinx, the which command won't show you the location on the package interface directly:

   which Sphinx

What you're looking for instead is the sphinx-build executable:

   which sphinx-build
   /usr/local/bin/sphinx-build

And it is the sphinx-build executable that you can query for help when starting and stopping the system:

   which sphinx-build --help

And so on.

Using easy_install with an explicit version of Python

It is possible to have multiple versions of Pyton installed on your system:

   $ ls -1 /usr/bin/py*
   /usr/bin/pydoc
   /usr/bin/pydoc2.5
   /usr/bin/pydoc2.6
   /usr/bin/python
   /usr/bin/python-config
   /usr/bin/python2.5
   /usr/bin/python2.5-config
   /usr/bin/python2.6
   /usr/bin/python2.6-config
   /usr/bin/pythonw
   /usr/bin/pythonw2.5
   /usr/bin/pythonw2.6

This can be a problem when you use easy_install to install a new Python package:

   easy_install -U Sphinx

Fortunately, you will find multiple versions of easy_install on your machine:

   $ ls -1 /usr/bin/easy_install*
   /usr/bin/easy_install     
   /usr/bin/easy_install-2.5 
   /usr/bin/easy_install-2.6

This makes it possible to use easy_install with an explicit version of Python:

   $ easy_install-2.6 -U Sphinx

Installing sphinx and building docs

To install Sphinx, execute this from within any directory.

   sudo easy_install -U sphinx

To build the docs, change and then execute as follows.

   $ cd abjad/documentation/doc_sphinx

Then:

   $ make html

Sphinx runs for a while.

   sphinx-build -b html -d _build/doctrees   . _build/html
   Making output directory...
   Running Sphinx v0.6.1
   loading pickled environment... not found
   building [html]: targets for 460 source files that are out of date
   updating environment: 460 added, 0 changed, 0 removed
   reading sources... 
   [ 44%] chapters/api/tools/clonewp/by_leaf_counts_with_parentareading sources...
   [ 44%] chapters/api/tools/clonewp/by_leaf_range_with_parentag

And then finishes.