Uncategorized

Setting Up Sphinx Documentation

It took me a while to get Sphinx documentation set up correctly. Since it is highly configurable, it is highly easy to not configure correctly. In this guide I’ll assume that you’re using a Python virtual environment, and that you’ve placed the source code that you want to document in a directory called src/. I’ll walk through installing and configuring what you need to create documentation from inline comments using the Google or NumPy style, and create API documentation for a Flask server. I’ll be extra-explicit about what directory I’m in when I make calls that make assumptions about the working directory.

Initial Setup

I keep all my virtualenvs in my home directory at venvs/, so I would start this project by saying,

$ cd ~
$ virtualenv venvs/project

This will create a virtual environment in a new directory ~/venvs/project/. Go ahead and create a new directory at ~/venvs/project/src/ and add your source code. If your source code doesn’t have inline documentation, then you should add that now.

Installing Sphinx, napoleon, and autohttp.flask

First, go to the root of your project, and then install the following using the project’s pip. This will install Sphinx, and two extensions: napoleon, for Google and NumPy style documentation, and autohttp.flask for documenting the API of a Flask server.

$ cd ~/venvs/project
$ bin/pip2.7 install sphinx sphinxcontrib-napoleon sphinxcontrib-httpdomain

Set Up the docs/ Directory

Next, run the sphinx-quickstart and answer a bunch of questions about your project. At the very end, I say yes to autodoc, but no to everything else. If you followed most of the default options, this should create a docs/ directory containing a conf.py file and a bunch of .rst files.

$ cd ~/venvs/project
$ bin/sphinx-quickstart

Next, you’ll edit ~/venvs/project/docs/conf.py to tell it where your source code is, and what extensions to load. Open conf.py and edit so that it looks like the code below.

Lines 19-22 tell Sphinx where to find the source code. Lines 33-37 tell sphinx about the two extensions we’re interested in: autohttp.flask and napoleon.

# -*- coding: utf-8 -*-
#
# <Project> documentation build configuration file, created by
# sphinx-quickstart on Mon Nov 21 10:58:42 2016.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
#sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('../src'))

# -- General configuration ------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.autodoc',
    'sphinxcontrib.autohttp.flask',
    'sphinxcontrib.napoleon',
]

Build the Documentation

Next, you should build the project using the following command from the docs/ directory. This ensures that the documentation is built using the sphinx-build from the virtualenv.

$ cd ~/venvs/project/docs
$ make html SPHINXBUILD='../bin/sphinx-build'

Finally, you can view the HTML in the ~/venvs/project/docs/_build/html/ directory.

$ cd ~/venvs/project/docs
$ open _build/html/index.html

Debugging and Resources

Sphinx expects to be able to run your code, so if you have anything that depends on an external source, you need to include the dependencies, or be able to mock up some fake behavior. Here is the documentation I found to be most useful: