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.
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
$ 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:
# -*- 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
$ 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: