Documenting Python Module

Docstring Style Guide

There are many different docstring style guidelines.

We choose to follow the Google style guide for readability:

• Google style guide
• Sphinx example module

Auto-Doc Generation with sphinx

To create 'html' and 'pdf' documentation of our module, we use sphinx. Sphinx is a utility for generating python documentation that uses reStructured text (rst) files.

Installation

Install sphinx using pip

$ pip install Sphinx

Setting Up sphinx

To setup the documentation sources, first switch to the docs directory of the project. Then call sphinx-quickstart

$ mkdir docs
$ cd docs
$ sphinx-quickstart

Be sure to say yes to the "autodoc" extension. It is also recommend to separate the source and build directories.

sphinx-quickstart should generate

• Makefile - a makefile for building the documention (i.e. call $ make html$ to build html documentation)
• conf.py - a configuration file for sphinx. Edit this to change settings and add extensions
• index.rst - the home page for documentation

To get "autodoc" to recognize the Google style, enable sphinx.ext.napoleon by editing conf.py. See sphinx support for Google style docstrings for more details.

Adding Module Documentation

To add documentation, we can either modify rst files manually or use sphinx-apidoc (example_link, apidoc documentation) .

I recommend using sphinx-apidoc to generate the rst files and then modify them manually. To create documentation call

$ sphinx-apidoc -o <outputdir> <sourcedir>

where <sourcedir> is the path to the module folder (e.g. src/) and <outputdir> is docs/source. Note that sphinx-apidoc will import each module in <sourcedir>.

Useful sphinx-apidoc options (--separate for separate pages and --private to include all functions)

Documentation Output Formatting

To change the html output style, change sthe html_theme value in conf.py. (http://www.sphinx-doc.org/en/stable/theming.html)

Documentation for Cython Extensions

To Do.

It looks like we just need to remember to call python setup.py build_ext --inplace before building with sphinx.

See GitHub Example or Stackoverflow

Automating Sphinx Publishing to Github Pages

(http://www.willmcginnis.com/2016/02/29/automating-documentation-workflow-with-sphinx-and-github-pages/)