Write Documentation for Python Packages Using Sphinx

Things on this page are fragmentary and immature notes/thoughts of the author. Please read with your own judgement!

Installation¶

You can install Sphinx and necessary extensions using the following command.

:::bash
pip3 install sphinx sphinx-autodoc-typehints

Or simply

:::bash
xinstall sphinx -ic

Since the above commands installs Sphinx to the user’s local directory, Sphinx executables are placed into the directory ~/.local/bin. So you might have to configure your PATH environment variable so that you can use Sphinx commands directly.

Generate Docs Using Sphinx¶

Create a directory named docs in the root directory of your Python project. Do NOT use the root directory of your project as the root directory for documentations as it will make your the root directory of your project messy.
```
 :::bash 
 mkdir docs
```
Go to the directory docs and run the command sphinx-quickstart.
```
 :::bash 
 cd docs 
 sphinx-quickstart 
```
A few questions will be asked to you. Note: It is suggested that you choose to separate build and source directories when the question is asked. This option makes the docs directory tidier especially for large projects.

Update the generated configuration script conf.py. Below are a few important ones.

Configure sys.path to tell autodoc where to find your code. In short, you should insert the path to your source code directory as the first element to sys.path. Relative paths (w.r.t the directory of the file conf.py) are allowed. Assume your project has the following structure,
```
  :::text
  proj_name/
      proj_name/
          __init__.py
      docs/
      ...
```
you can use the following generic code to help you to insert the correct path of the source code directory.
```
  :::python
  import sys
  from pathlib import Path


  def get_source_dir() -> str:
      path = Path(__file__).resolve()
      while path.name != "docs":
          path = path.parent
      return str(path.parent)


  sys.path.insert(0, get_source_dir())
```

Enable sphinx extensions.

  :::python
  extensions = [
      "sphinx.ext.todo",
      "sphinx.ext.viewcode",
      "sphinx.ext.autodoc",
      "sphinx_autodoc_typehints",
      "sphinx.ext.doctest",
  ]

Run the following command in the docs directory to generate documentation from docstrings. Notice that the command sphinx-apidoc does not extract docstrings from your source code but instead generate a RST file to tell Sphinx to use docstrings when building the docs. So you only have to run the command aphinx-apidoc once.
```
 :::bash
 # if build and source are NOT separated
 sphinx-apidoc -f -o ./ ../proj_name
 # if build and source are separated
 sphinx-apidoc -f -o source/ ../proj_name
```
A file named modules.rst (together with some other RST files) will be generated. Include it into the file index.rst.
Add more RST files into index.rst if necessary.
Run the following command in the docs directory to generate HTML documentation.
```
 :::bash 
 make clean && make html 
```