Quick setup of sphinx documentation

sphinx is a great and versatile tool. Not only does it create simple but easy to read (python) code documentation. One can use sphinx to produce a readme, a manual, notes, minutes, etc., that go beyond the simple ascii format with just a little bit of effort. Most of the content of existing ascii files are already in a suitable format for sphinx. Compared to LaTeX, the extra work beyond actually writing the content is minimal. In fact, sphinx can automatically produce quite decent LaTeX output. And html, xml and other formats.

However, I found it a bit tricky to set up a sphinx directory, and it took me half a day to get going. Online documentation is quite decent, but did not present in a concise and easy-to-understand way what I wanted, that is, to quickly create a sphinx parent document for my python coding projects. So here is a summary of the steps I needed to do.

First, the case where existing files are to be included in a sphinx document (file index.rst). For example, python scripts and modules that already have sphinx-compatible documentation.

  1. Install sphinx if not already existing, for example using port (on a Mac) or pip.
  2. From the directory where the scripts are located, say ‘/path/to/scripts’, create a sub-directory ‘docs’ (or any other name).
  3. In /path/to/scripts, run

    sphinx-apidoc -A “Author name” -H “Project name” -F -o docs .

    On some systems, the command might be sphinx-apidoc-X.Y’ where ‘X.Y’ is the active python version. This creates various files and directories in ‘docs’, in particular the configuration file ‘conf.py’, and the actual sphinx parent document ‘index.rst’, which automatically contains references to all scripts in ‘/path/to/scripts’.

  4. Add path to the scripts to the sphinx configuration file docs/conf.py. From ‘docs’, the relative path is ‘..’, and the line to be added is:

    sys.path.insert(0, os.path.abspath(‘..’))

  5. [optional] Add path(s) to further scripts, e.g. modules that are included in the python scripts. In ‘docs/conf.py’, add a new line:

    sys.path.insert(0, os.path.abspath(‘/path/to/mores/files’))

  6. In ‘docs’, run

    make html

Done! The file ‘_build/html/index.html’ (in ‘docs/’) contains the html version of the code documentation. Open this file in your browser, e.g. from Terminal on a Mac:

open _build/html/index.html

Other output format can be created by replacing ‘html’ in step 6 with e.g. ‘latex’, ‘latexpdf’, etc. See ‘docs/Makefile’ for all possible options.

Further posts will describe how to quickly create conference (or other) notes, include references using bibtex, and actually create a sphinx (html) document containing all references with links to the papers from a bibtex file.