Contents

Sphinx Autodoc (Optional)

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

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

Note

  • (base) indicates the conda environment you are using.

  • {username} shows your username.

  • {hostname} shows the name of the server running your jupyter environment.

  • {cd} shows your current directory. By default, it shows ~, which is an alias of your home directory /home/{username}.

  • ▯ is the cursor, where you can run a bash command.

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

Tip

  • You need to press enter to execute the command.

  • ~/docs expands to /home/{username}/docs.

  • You can learn more about a command by running it with the option --help such as

    sphinx-quickstart --help

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.

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y

The project name will occur in several places in the built documentation.
> Project name: Recurtools
> Author name(s): CHAN Chung
> Project release []: beta

Note

  • Project release specifies the full project version. See software versioning for the convention.

  • If successful, the command will print the message

    Finished: An initial directory structure has been created.

How to build the documentation?

Run the build script：

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

Note

The command uses the html builder to generate static webpages to ~/docs/recurtools based on the configuration from ~/docs/source.

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 cs1302/Lab6/conf.py.

Path setup

Uncomment and modify the relevant lines as follows to add the module path to the system path:

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

Note

  • The module path ~/cs1302/Lecture6 contains the recurtools module.

  • The module path is searched first as it is added to the beginning of the system path.

General configuration

Add the necessary extensions as follows to extensions:

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

Note

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

exclude_patterns = ['**.ipynb_checkpoints']

Note

.ipynb_checkpoints keep a backup of your files so you may recover them. However, sphinx will build documentation on those backup files unless we exclude them explicitly.

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/Lecture6

Note

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

Lecture6
========

.. toctree::
   :maxdepth: 4

   recurtools

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`

Tip

  • Note that there is no need to add the extension .rst as it is the default.

  • modules is the content of the directive toctree. It must have the same indentation as the arguments :maxdepth: and :caption: above and must be separated by a blank line.

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.