Sphinx Autodoc (Optional)

CS1302 Introduction to Computer Programming

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

• Python (src)
• Numpy (src)
• Pandas (src)

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

Getting started¶

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}$ ▯

How to install sphinx?

There are many ways to install sphinx as detailed in the documentation. E.g., you can install Sphinx using pip, which is the Python package installer. Run the following command:

pip install sphinx

This command installs sphinx globally. Note that restarting your jupyter server will erase global packages you installed. To install it locally to your home directory, you can create and activate a conda environment:

• You can create a new conda environment named sphinx with the following command:

  conda create --name sphinx

• Before you can use this environment and install packages into it, you need to activate it. You can do this with the following command:

  conda activate sphinx

• Now you can install Sphinx into the "sphinx" environment by running the following command:

  conda install sphinx

You can now start creating the document as described below. When you are done using sphinx, you can deactivate the environment using the command:

conda deactivate

How to configure sphinx?

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.

How to build the documentation?

Run the build script：

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

How to preview the documentation?

You can view the documentation by

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

The documentation is currently empty because we have not specified the module to document.

Autodoc¶

How to configure sphinx to document a module automatically from its docstrings?

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.

Path setup

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

import os
import sys
sys.path.insert(0, os.path.expanduser('~/cs1302_23a/Lecture6'))

General configuration

Add the necessary extensions as follows to extensions:

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

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

exclude_patterns = ['**.ipynb_checkpoints']

How to generate the documentation from docstrings?

Run API documentation command to create the rst files for recurtools:

sphinx-apidoc -f -o ~/docs/source ~/cs1302_23a/Lecture6

Modify index.rst to point to modules.rst as follows:

.. Recurtools 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 Recurtools'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/recurtools

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

Exercise (optional)

Create a module combinatorics for the functions in Lab 6 and document them together with recurtools in Lecture 6.