Documentation using Sphinx

Sphinx is a free, online tool that helps generate documentation for primarily Python projects.  We use it for HTML format outputs, but it also supports LaTeX, ePub, Texinfo, manual pages, and plain text formats.  The markup language of Sphinx is reStructuredText (reST) (for documentation see http://sphinx-doc.org/rest.html).  Of Sphinx’s many features, the one most useful thus far is its auto-documentation of Python files, the steps of which this post details below.

Sphinx auto-documentation steps:

  1. Install Sphinx at the command line using: easy_install -U Sphinx
  2. Read through the Sphinx documentation at http://sphinx-doc.org/.
  3. Run Sphinx’s Getting Started function Sphinx-quickstart to quickly set up directories and configurations. NOTE: Since I have already completed this setup, it DOES NOT need to be run again for the BDNYC documentation.
    1. Access the documentation directories in Dropbox through the shared folder BDNYCdb/Documentation
    2. The Documentation folder contains the .rst and .py files that Sphinx uses to build documentation.  Place any files for which documentation is to be made within that directory since Sphinx automatically looks there.
      Screen Shot 2014-08-07 at 2.46.31 PMBDdb.html within the Documentation directories
  4. The index.rst file is the master file that contains the table of contents (known as a TOCtree) for the entire documentation.  Within  the TOCtree, Sphinx knows that all the files are .rst, so there is no need to specify the file extension or path.  The index also serves as a welcome page for users, so it may include an introduction or other information that would be useful for outside reference.  Within the TOCtree (and all of reST) indentation and notation is especially important.  Below is an example of a functioning TOCtree.  .. toctree::
    :maxdepth: 2
    # blank line
    BDdb
    utilities
    astrotools
    load_db
    Database_instructions

    The “maxdepth” function specifies the depth of nesting allowed.  In order to keep the index clean and aesthetically simple, a maximum of one nested page is reasonable. In other files, however, highly nested pages are not only common, but well-supported by reST.

    Screen Shot 2014-08-07 at 2.52.07 PM
    Screenshot of index.rst
  5. For each item in the TOCtree of the index file, there must be a corresponding .rst file in the main directory for Sphinx to nest within the index HTML file.  In the above example, a Database_instructions.rst file might contain in plain English how to interact with the database, while the BDdb.rst file contains the auto-documentation of BDdb.py.
  6. The .rst file within the TOCtree of the index must be formatted like below to correctly call for the Python files. [name of module]
    ================    # make page header (see http://sphinx-doc.org/rest.html)
    .. automodule:: [name of Python file w/o extension]
    :members:    # tells Sphinx to pull from the file
    # blank line
    :undoc-members:
    :show-inheritance:

    Screen Shot 2014-08-07 at 2.57.41 PM

    Screenshot of BDdb.rst

  7. The referenced Python files for auto-documentation can either be in located in the main directory, or their location can be specified.  Since we will be constantly pushing and pulling from Github, it is best for those doing documentation to change the file path to their local copy of BDdb.py, astrotools.py, etc, before making documentation.  This can be achieved as follows:
  8. Open conf.py, which is the configuration file for Sphinx.  It was produced during the “quickstart” function to allow easy modifications of aesthetic features (i.e., theme, font), and facilitate the HTML building process.
    1. Change the file path in line 21 to the applicable local copy.
    2. Comment out the file path of previous users in order to make it easier for others to update documentation.
  9. In order to make the HTML files, move Terminal to the directory of the documentation, i.e., ‘…/Dropbox/BDNYCdb/Documentation’ and run make html.
    1. The make htmlfunction comes build-in through running “quickstart” and uses the makefile in the main directory.  It can take other functions as well, including make clean, which deletes the entire contents of the “build” directory.
    2. Sphinx should put the generated HTML files in the /_build/html directory.
  10. To make the HTML files live on BDNYC.org/database, use the application Cyberduck, which can be downloaded at http://cyberduck.en.softonic.com/mac.
    1. Click “Open Connection” and put in the server, username, and password.
    2. Drag and drop any .rst and HTML files that were modified into the appropriate directory and the documentation should go live immediately!

 

References:

http://sphinx-doc.org/ — Sphinx documentation homepage

http://sphinx-doc.org/contents.html — Outline of Sphinx documentation

http://sphinx-doc.org/rest.html — Using reStructuredText in Sphinx

http://sphinx-doc.org/ext/autodoc.html — Auto-documentation documentation

http://cyberduck.en.softonic.com/mac — Download Cyberduck

Leave a Reply

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