Write and Publish Python Code Documentation Automatically

We all know that programmers write code but many of us are not aware that they read more than write. The clean code will be easier to read. In this article, I am going to explain about the process of writing and publishing the python code documentation easy and effective way. Below is the table of content,

1. Write the standard docstring
2. Install Sphinx
3. Initialize Sphinx
4. Update the conf.py file
5. Auto generate the rst file
6. Build HTML
7. Publish the documentation online
8. Reference

1. Write the standard docstring

Good programmers prefer to write the logic behind each class, methods, function etc using comments. In python, the best way to add the comments for the functions or class is to write in docstring format. Later, it can be used by documentation automation tools like sphnix to generate the document. But for the automation, you should follow the standard docstring guideline. Here is the small example of good docstring example,

def add(x, y):
    """Function to add two numbers 

        Parameters
        ----------
        x: int
            First number to add
        y: int
            Second number to add

        Returns
        -------
        int
            The sum of x and y
        """
    return x + y

2. Install sphinx

Now next step is to install the sphnix. It can be installed easily using pip command,

pip install sphinx

3. Initialize the sphinx

In the root directory of your project, run sphinx-quickstart to initialize the sphinx source directory to create a default configuration. I prefer to have separated directory for build and source, I hope you will also do the same.

sphinx-quickstart

Below image is the example of my sphinx-quickstart,

As shown above, running the sphinx-build command creates a Makefile, a make.bat file, as well as build and source directories.

4. Update the conf.py file

The conf.py file is inside the source folder which describes the sphinx configurations to control the documentation. Here, I recommend you to overwrite the following things,

Add project information

In the project information section, you need to update about copyright, author, release etc. Following is the example of my project information,

# -- Project information -----------------------------------------------------

project = 'GeoTile'
copyright = '2022, Tek Kshetri'
author = 'Tek Kshetri'

# The full version, including alpha/beta/rc tags
release = '0.1.0'

Add extensions

By default, there will be no extension added to the documentation. You have to add at least following extension to generate the documentation

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

Update theme

The default theme for sphinx is alabaster. There are several other themes are available, but personally, I like pydata_sphinx_theme. To change the theme, you need to install it first using terminal,

pip install pydata_sphinx_theme

And update it to the conf.py file,

# html theme for documentation
html_theme = "pydata_sphinx_theme"

There are several ways to customize this theme. If you are interested, please check the official documentation of pydata_sphinx_theme

Specify the location of the python modules

At the top of the conf.py file, you will see some commented line of code. If your python code path is outside the documentation directory (Most of the case is like this), you have to specify the path to the code like below,

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))

Here is my folder structure,

5. Auto generate the rst file

Sphinx generates the HTML documentation from reStructuredText (rst) files. To autogenerate the rst files, run the sphinx-apidoc command using following syntax:

sphinx-apidoc -o <OUTPUT_PATH> <MODULE_PATH>

In my case, the output directory is source, and the module directory is testCode. I have to run following command from documentation root folder,

sphinx-apidoc -f -o source ../testCode

The above command will create at least two files, modules.rst and test.rst. You can open it with any text editor and see the configuration or manually edit the things as well.

6. Build HTML

Before building the HTML document, we need to insert the modules.rst file to source/index.rst file toctree. Please add the API reference <modules> to toctree as below,

.. toctree::
   :maxdepth: 2
   :caption: Test Documentation

   API reference <modules>

After that run the following command from your documentation root directory,

make html

This command will generate the html file inside the build directory. You can open it with any browser to check the documentation.

7. Publish the documentation online

To publish the documentation, I am going to use Read the Docs open-source solution. Using read the docs, you can publish your documentation free of cost. Here is the guideline for publishing,

Create account

If you don't have read the docs account, create account and login to the read the docs site.

Import project

In your user dashboard, there is option to Import a Project. Click the option, again click on Import Manually button. Add the project name, repository URL (GitHub url to your documentation), and default branch and click next.

Again add the extra details about your project.

The final step is to build the version and view the docs,

If you did everything correctly, live version of your documentation will be rendered after clicking view docs button.

I hope this blog post is informative for you. If you like this blog, please support me by subscribing to my YouTube channel: https://www.youtube.com/c/iamtekson

8. Reference

1. Documenting python code (Blog post)
2. Automatic documentation generation from code (official documentation)
3. RST documentation guidline