---
jupytext:
  text_representation:
    extension: .md
    format_name: myst
    format_version: 0.13
    jupytext_version: 1.11.5
kernelspec:
  display_name: Python 3 (ipykernel)
  language: python
  name: python3
---

# Sphinx Autodoc (Optional)

+++ {"slideshow": {"slide_type": "-"}, "tags": ["remove-cell"]}

**CS1302 Introduction to Computer Programming**
___

+++

[Sphinx](https://www.sphinx-doc.org/en/master/index.html) is a tool to generate high-quality documentations such as:
 - [Python](https://docs.python.org/3/)
 - [Numpy](https://numpy.org/doc/stable/)
 - [Pandas](https://pandas.pydata.org/docs/)

+++

Sphinx provides an extension called [autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) 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](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html#managing-environments) 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](https://en.wikipedia.org/wiki/Bash_(Unix_shell)).

````

+++

**How to configure sphinx?**

+++ {"tags": []}

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

```Bash
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  
    ```Bash
    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](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-release) specifies the full project version. See [software versioning](https://en.wikipedia.org/wiki/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：

```Bash
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**

+++ {"tags": []}

Uncomment and modify the relevant lines as follows to add the module path to the system path:  
```Python
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`:
```Python
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
```

+++

````{note}

- [`sphinx.ext.autodoc`](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) generates documentation from docstrings in [reStructuredText format (rst)](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) format, which is powerful but makes the docstrings difficult to read.
- [`sphinx.ext.napoleon`](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html) converts the more readable Numpy-style and Google-style docstrings to rst.

````

+++

Change [`exclude_patterns`](https://nbsphinx.readthedocs.io/en/0.5.0/usage.html#exclude_patterns) to exclude temporary files in the hidden `.ipynb_checkpoints` folder:  
```Bash
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`:  
```Bash
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:

```Markdown
Lecture6
========

.. toctree::
   :maxdepth: 4

   recurtools
```

````

+++

Modify `index.rst` to point to `modules.rst` as follows:  
```Markdown
.. 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  
```Bash
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.