Using Sphinx to Document Python Projects with Google Doctrings

1. Make sure you have installed all dependencies used by the project. This is easily accomplished with pip install <module_name>

2. See First Steps with Sphinx for an overview on how Sphinx works. Essentially, Sphinx uses a markup language called reStructuredText to create nice looking documentation. It will be helpful to read about the function of the master document index.rst so that you can understand how the toctree works.

3. Install Sphinx with pip install sphinx

4. To get Sphinx setup, sphinx-quickstart. This will ask several questions about the project. To make the file tree cleaner, I think it's good to separate the respond to Separate source and build directories (y/n) with y. Sphinx's Autodoc extension automatically generates the reStructuredText needed for Sphinx to build the documentation from docstrings, so when asked autodoc: automatically insert docstrings from modules (y/n), respond y.

5. In order to generate documentation using Google-style docstrings, we need to use the Napoleon extension. In order for Napoleon to work, we need to edit conf.py to include the following information:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon'
]

napoleon_google_docstring = True
napoleon_numpy_docstring = False
napoleon_include_init_with_doc = True
napoleon_include_private_with_doc = False

6. As explained in An Idiot's Guide to Python Documentation with Sphinx and ReadTheDocs, we can automatically generate the necessary reStructuredText by calling sphinx-apidoc -o source/ ../<package_name>. This will create a few .rst files with directives telling autodoc what files it should create documentation from.

7. In order for Sphinx to know it should act on the directives in these new .rst files, they need to be added to the toctree in index.rst. Basically, you just edit index.rst and add the names of the new .rst files below the line reading .. toctree::. For example, if we just want to document a package contained in a single folder called package, we the toctree directive in our index.rst file might look like this:

.. toctree:
    :maxdepth: 2

    package
    modules

8. Before we can build the documentation, we need to make sure Sphinx knows where to get the modules from. In conf.py, the following three lines are commented out by default:

import os 
import sys 
sys.path.insert(0, os.path.abspath('.'))

As noted in a stackoverflow post about this, if our project has the structure

project
    | docs/
    | project/
        | project files, etc.
    | tests/

we need to uncomment those three lines in conf.py and change the third line about changing the path to sys.path.insert(0, os.path.abspath('../..')).

9. Now, we're ready to build the documentation. To create HTML documentation, go to the directory with Makefile and call make html. This will create a folder build/html/ with the documentation. To view it, go to that directory and launch python's simple web server using sudo python -m SimpleHTTPServer 80, which will host the documentation website on your local machine. You can then navigate to the webpage by going to localhost in your browser.

10. For details on how to use the ReadTheDocs Theme, see Read the Docs Sphinx Theme