Sphinx Autodoc

Sphinx is a tool to generate high-quality documentations such as the documentations for:

• Python (repository)
• Numpy (repository)
• Pandas (repository)

Sphinx provides an extension called autodoc that can automatically generate documentations from the docstrings of a module. We will use it to document our Lecture6 module used in Lecture 6.

Quick Start¶

We will run the sphinx in the terminal. To start a termial session in JupyterLab:

• Open the Launcher (File->New Launcher).
• Start a new termial session by clicking the Terminal icon under Other.

You should see the terminal tab with a prompt for your input:

(base) {username}@{hostname}:{cd}$ ▯

Run the following quick-start command in a terminal to create the configuration files in a folder called docs under your home directory:

sphinx-quickstart ~/docs

You will be asked a few questions:

• Answer y to the first question to use separate source and build directories.
• Answer whatever you desire for the remaining questions.

If successful, the command will print the message:

Finished: An initial directory structure has been created.

You can then run the build script to generate the documentation:

sphinx-build -b html ~/docs/source ~/www/Lecture6

You can view the documentation by

• clicking File->New Launcher, and
• clicking the icon www and then folder Lecture6.

Autodoc¶

The documentation is currently empty because no module has been specified for documentation. Sphinx supports extensions that can automatically generate documentation files for a specified module.

Path setup¶

From the File Browser tab, navigate to the docs/source folder under your home directory and open conf.py by double clicking it and modify it as follows. A sample can be found in conf.py.

Add the module path to the system path at the beginning of the configure file:

import os
import sys

path = os.path.expanduser('~/${COURSE_ID}')
path = os.path.expandvars(path)
sys.path.insert(0, path)

The module path should contain the top-level module to be documented:

The module path is searched first as it is added to the beginning of the system path with sys.path.insert(0, path).

Configuration¶

Add the necessary extensions as follows to extensions:

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

• sphinx.ext.napoleon converts the Numpy-style and Google-style docstrings to rst-formatted docstrings.
• sphinx.ext.autodoc generates documentation from docstrings in reStructuredText format (rst) format.

Change exclude_patterns to exclude temporary files in the hidden folder .ipynb_checkpoints:

exclude_patterns = ['**/.ipynb_checkpoints']

Building the documentation¶

Run API documentation command in a terminal to create the rst files for Lecture6:

sphinx-apidoc -f -o ~/docs/source ~/${COURSE_ID}/Lecture6

The above creates modules.rst and Lecture6.rst under ~/docs/source. In particular, modules.rst points to Lecture6.rst as follows:

Lecture6
========

.. toctree::
   :maxdepth: 4

   Lecture6

Sphinx does not automatically include modules.rst in the documentation, i.e., building the documentation now will not show any modules. The user must design the structure of the documentation and include modules.rst manually.

The simplest way to add modules.rst to the table of content (toctree) in index.rst, which is the main page of the document:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
.. Lecture6 documentation master file, created by
   sphinx-quickstart on Sun Oct 31 11:51:38 2021.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Lecture6's documentation!
======================================

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

   modules

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Rebuild the documentation with

sphinx-build -b html ~/docs/source ~/www/Lecture6

Preview the documentation again by refreshing or relaunching the www page.