Stephanie M. Sherman, Ph.D.

Summary

This post describes how to generate, customize, and maintain python repository documentation generated by Sphinx.

Setup

Create a conda environment yaml file called doc_env.yml

name: doc_env
channels:
  - conda-forge
  - defaults
  - mro
dependencies:
  - boto3=1.9.*
  - jupyterlab=0.35.*
  - matplotlib=3.0.*
  - pandas=0.24.*
  - python=3.7.*
  - seaborn=0.9.*
  - pip=19.0.*
  - pip:
      - snowflake-connector-python==1.7.*
      - sphinx==1.8.*
      - sphinx_rtd_theme

Create and activate the conda environment (to learn more about conda environments check out an earlier post)

conda env create -f doc_env.yml
conda activate doc_env

Getting Started

Let’s say you have a repository of code called sphinx_test_repo that contains a modules directory with two .py files – utility_functions.py and examples.py. These files contain python functions that have numpy style docstrings. In your repos directory create a docs folder and move into it:

mkdir docs
cd docs
sphinx-quickstart

Sphinx Configuration

• Below are some useful settings for the quick-start
  • Create separate source and build directories
  • Useful sphinx extensions:
    • autodoc – automatically builds out module index
    • intersphinx – add links to external docs cross-reference
    • todo: shows Todo entries
    • viewcode – add links to source code
    • napoleon – allows you to write numpy or google style docstrings

Explore sphinx-quickstart the directory structure

docs
└── Makefile 
└── source
         └── conf.py
         └── index.rst
         └── _static
         └── _templates
└── build

Customize conf.py

1. In the source folder open conf.py so we can configure sphinx to look how we want
2. Under Path Setup uncomment the imports and sys.path and change it to sys.path.insert(0, os.path.abspath('../../modules'))
   to reflect where the modules live
3. If the quickstart does not include the napoleon extension add 'sphinx.ext.napoleon' to extension list and under extension add:
   1. napoleon_google_docstring = False
   2. napoleon_use_param = False
   3. napoleon_use_ivar = True
   4. Learn about these settings here
4. To use the sphinx rtd theme:
   1. html_theme = 'sphinx_rtd_theme'
   2. pygments_style = 'sphinx'
5. Add to the html_theme_options
6. Add intersphinx mapping – examples below:

intersphinx_mapping = {'python': ('https://docs.python.org', None),
                        'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None),
                        'numpy': ('http://docs.scipy.org/doc/numpy/', None),
                        'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None),
                        'sklearn': ('http://scikit-learn.org/stable/', None),
                        'matplotlib': ('http://matplotlib.org/', None),
                        'seaborn': ('https://seaborn.pydata.org/', None)}

Build docs for repo modules

Now that we have done some configuration on the documentation lets build it using autodocs! In docs directory:

sphinx-apidoc -o source/ ../modules/

Generate documentation

Go to the docs folder where you see the Makefile and run:

make html
open build/html/index.html

Edit home page

Open the home page (defaults to source/index.rst). Under the toctree setup add the names of the files.

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   utility_functions
   examples

Now you can reopen the index and enjoy your documentation!

References

• https://www.divio.com/blog/documentation/
• https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs/