Documenting Python Code With Sphinx

How to write Python code to automatically create documentation

Sphinx is a tool to create documentation for Python projects. It creates HTML documentation directly from docstrings.

We'll use the project of the CoinGecko API to show how to use Sphinx to create stunning documentation for Python projects.

---

Prerequisites

Before using Sphynx you have to create and activate a virtual environment.

This section shows how to do so in Windows and Linux. So, if you already know it you can skip it.

Creating a virtual environment on a Windows machine

Step 1: install virtualenv

> pip install virtualenv

Step 2: create the virtual environment

Go to the directory where you want to create the virtual environment. Suppose, in that directory, you want to create a directory venv then type:

> python -m venv venv

This code creates a folder called venv which contains everything you need for your virtual environment.

Step 3: activate the virtual environment

Remain in the same folder you are in and type:

> venv/Scripts/activate

Creating a virtual environment on a Linux machine

Step 1: verify you need any updates

$ sudo apt-get update

Step 2: install the virtual environment packages

$ sudo apt install python3-venv

Step 3: create the virtual environment

Go to the directory where you want to create the virtual environment. Suppose, in that directory, you want to create a directory venv then type:

$ python3 -m venv venv

This code creates a folder called venv which contains everything you need for your virtual environment.

Step 4: activate the virtual environment

Remain in the same folder you are in and type:

$ source venv/bin/activate

---

How to use Sphinx

To use Sphinx to create documentation for your Python code, follow this procedure.

Step 1: activate a virtual environment and create a /docs folder

Open a CLI and, after activating the virtual environment, create a /docs folder in the main folder of your project.

Step 2: install Sphinx

Go to the /docs folder ( cd docs) and install Shinx as follows:

python -m pip install sphinx

Step 3: install the theme you like

Install the theme you like by choosing one from here.

In this example, we install the "Piccolo theme":

pip install piccolo-theme

Step 4: initialize Sphinx

Type the following to initialize Sphinx:

sphinx-quickstart

You’ll be asked some questions. Answer as follows:

• separate source and build directories? → y

• project name → (the name of your project)

• Author name → (the name of the author)

• project release → 0.0

• project language → press ENTER to leave it as English (default)

Now the /docs folder has been populated with the files and subfolders by Sphinx.

Copy all the files inside the /source folder in the /docs folder and delete the folder /source. Here's how the /docs folder should look like after that:

The /docs folder.

Step 5: first Sphinx command

Via CLI, go to the main folder of your project and type the following:

sphinx-apidoc -o docs .

Step 6: change the index.rst file

Inside /docs/source folder there is an index.rst file. You need this file to point to the modules.rst file.

So, open index.rst, for example via VS CODE, and write module as follows:

How to modify the index.rst file.

Step 7: change the conf.py file

Inside /docs/source folder there is an conf.py file.

This is what it looks like:

How the conf.py file appears whwn you open it.

Modify it as follows:

• Change extensions = [] in extensions = ["sphinx.ext.todo", "sphinx.ext.viewcode", "sphinx.ext.autodoc"].

• Change html_theme = 'alabaster' by inserting the theme you choose. We've chosen the "Piccolo theme" so we change it to html_theme = 'piccolo_theme'.

• Tell the program, in the beginning of it, to use the absolute path like so: import os

  import sys

  sys.path.insert(0, os.path.abspath(".."))

So, this is how the conf.py file looks like after the modifications:

The conf.py file after the modifications.

Step 8: create the build

Verify you're in the main folder of the project and type the following:

sphinx-build -M html docs docs/build/html

Now, inside docs\build\html\html you find a index.html file: open with your browse to visualize the code documentation.

This is how the documentation of your Python project looks like when you open it:

How your Python project shows the documentation thanks to Sphinx.

Of course, to reach this result, you must implement best practices like docstrings and type hints as PEP8 recommends.

WARNINGS:

1) I recommend using Sphinx when you're sure the project is frozen for quite some time. Otherwise, at each code change, you must re-build the project (in this case, you'll increment the review number described in step 4 from 0.0 to 1.0 or whatever the review number it should be for your case).

2) After installing Sphinx and the theme you've chosen for the first time, of course, you don't need to do so anymore. So, after the second time, you can start from step 4 of this guide.

NOTE: if you're wondering if you can use custom CSS because, for example, you want to use some particular fonts, the answer is yes. All you have to do is:

1) Create a custom CSS file with the fonts you want to use. Suppose you call it custom.css file. You have to save it in the folder docs/_static/.

2) At the bottom of the config.py file, right after html_static_path = ['_static'], paste html_css_files = ["custom.css"]