Sphinx: Create Beautiful Python Documentation

Sphinx is a third-party Python module used to generate documentation pages using a universally-recognized format. Both bdnyc.org/astrotools and bdnyc.org/database are generated with Sphinx.

Once Sphinx is properly installed in your computer, generating the documentation is extremely easy. The tricky part is to install Sphinx and all of the stuff it requires. So pay attention.

Installing Sphinx
First, install the latest version of the peripheries that Sphinx will use. These are docutils (a text processing system) and Jinja2 (a templating language). If you have iPython set up, then this is very easy. Just type in your terminal window:

> sudo easy_install -U docutils

> sudo easy_install -U Jinja2

If this does not work, then do the following:
For docutils, download the latest release package and run the install.py file in your iPython session.
For Jinja2, download the latest release package and run the setup.py file in your iPython session.

Second, install Sphinx. To do this, again, use easy_install:
> sudo easy_install -U Sphinx

Third, run the script that initializes Sphinx files and folders for a project. This script only needs to be run once per project. Run it inside the folder where you want the documentation files to reside (e.g. /Users/alejo/Sphinx_docs/astrotools/). In your terminal window, type:
> sphinx-quickstart

This script will ask you a set of questions, all of which have a default answer. Answer all of them using the default by pressing Enter each time, EXCEPT for the following three questions:

  • when it asks to install the autodoc extension, answer YES
  • when it asks to install intersphinx, answer YES
  • when it asks to install coverage, answer YES

When the script finishes, you will notice that your current folder now has the folders _static/ and _templates/, and the files conf.py, index.rst, make.bat, and Makefile. You are done setting up Sphinx.

Using Sphinx
The beauty of Sphinx is that it reads the docstrings in your Python modules (all those lines wrapped around with three quotation marks) and generates the whole shebang automatically. The only important thing to remember is that these docstrings should follow reStructuredText syntax. No panic! It is very simple. For instance, if you want a word in italics, you write: *word*. Consult the reStructuredText User Reference for more information.

The master document that Sphinx uses to generate everything is index.rst. In it, you will see the lines:

.. toctree::
…….:maxdepth: 2

Now, to read the docstrings from a module, say, astrotools, enter the following lines below the two lines above:

.. automodule:: astrotools

Indentation is important. Make sure that the first “:” in the second row aligns with the “a” in “automodule”. Also, make sure that Sphinx has access to the module, that is, that the path where the module resides is one of your Python paths (To test this, try importing astrotools from ANY folder; if it works, then you are good to go). Save the changes in index.rst.

Finally, to generate the documentation, type in your terminal window:
> sphinx-build -b html . build/

Sphinx will generate all the necessary files and store them in a new folder called build/.

To see the output, open the index.html file in the build/ folder. This is the main html page of the documentation.

Updating bdnyc.org Python documentation
To update the astrotools and database documentations in bdnyc.org, you need to synchronize the build/ folders in your computer (where their Sphinx documentation reside) with their folders on the website: /bdnyc/astrotools/ and /bdnyc/database/ via ftp.

In a later post, I will elaborate more on the index.rst file, since there are so many cool things that you can include in it to make your html pages better.

Leave a Reply

Your email address will not be published. Required fields are marked *