Sphinx

Webapp

• We use sphinx to generate our documentation
• We use Azure webapps to host it

Contribution

Most of the process can be automated by CI/CD pipeline:

• Build docstrings
• Builds the html files

There are a few things to understand how to use it.

The layout

Suppose you have a library like this:

my-repo/
    requirements.txt  # reqs for src code to run
    src/
        # my library is here
    docs/
        # create this for your documentation

We will generate / create the following under docs:

docs/
    index.rst  # this is the master table of contents
    conf.py  # configuration for sphinx
    requirements.txt  # specific reqs for documentation
    source/  # directory where docstring files are automatically generated by sphinx
    example.md  # markdown or rst files can be included here
    ...  # other files can largely be ignored

How to add a new file

0. Set up a python environment as follows:

   conda create --name elr2-sphinx python=3.8
   conda activate elr2-sphinx
   pip install -r requirements.txt  # elr2 requirements
   pip install -r docs/requirements.txt  # sphinx requirements

1. Create a new file e.g. docs/example.md

   • You can also use .rst if you like

2. Add this to the index.rst file

   You can add it to an existing section, or create a new one.

   .. toctree::
   :maxdepth: 1
   :caption: New Section
   
   example

3. To test your changes locally run make html:

   cd docs
   make html

   This will update the html files in docs/_build/html. You can open these files in your browser to test the changes / behavior.

4. Push your changes to master branch - the build pipeline will take care of the rest, i.e., it will push the changes to the webapp.

Setup

This describes how this was setup.

Run quickstart to generate sphinx project scaffolding:

cd docs
sphinx-quickstart

This will create conf.py and index.rst (among other things).

Update conf.py with the following:

import os
import sys
PATH_HERE = os.path.abspath(os.path.dirname(__file__))
PATH_ROOT = os.path.join(PATH_HERE, '..', '..')
sys.path.insert(0, os.path.abspath(PATH_ROOT))

extensions = [
    'sphinx.ext.napoleon',
    'sphinx.ext.autodoc',
    ... # added a bunch of extensions
]

napoleon_google_docstring = True

html_theme = 'sphinx_rtd_theme'

Update the index.rst file to have the desired layout for the homepage.

Now to generate the documentation run

cd webapp
sphinx-apidoc -o source ../src

This will scan ../src for python modules and put their docstrings in docs/source. You can see a bunch of .rst files in there now.

To build the html files manually you run

make html

This creates the html files in docs/_build/html.

Finally, to manually push these files to the azure webapp:

cd _build/html
az webapp up --name my-webapp --html

Note: Very rarely the az webapp up command might fail transiently - just re-run.