Documenting and Publishing Your Python Code

DOCUMENTING

Documentation of code in Python is done with the help of Docstrings which are descriptions provided in between """ right after the function, method or class definition. Two most popular Docstrings style that come highly recommended to follow are the Numpy-style Docstring and the Google Style Docstring. I prefer the Numpy-style but it is totally a personal preference. The idea is to select the style that suits you and be consistent throughout your code. The basic difference between these two styles are shown below:

Google-style Docstring


def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2
    Returns:
        bool: Description of return value
   """
   return True

Numpy-style Docstring


def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2
   """
   return True

AUTOGENERATING

Once you have proper Docstring in your code, you can use a Python library called "Sphinx" to autogenerate your documentation into a beautiful format such as html, latex etc. Sphinx is available in PyPI and you can install it using:

pip install -U sphinx

Basically, your workflow to include Sphinx in your project would involve the following:

1. Generate template files in your current directory

sphinx-quickstart

2. Edit conf.py, index.rst and add any rst file as needed
The above command generates conf.py and index.rst file to get started. In order for Sphinx to be able to read Numpy or Google Style Docstring, you will need to add the extension sphinx.ext.napoleon. Here is how my extensions list in conf.py looks like:


extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',  # extension that can read numpy or Google style docstring
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.mathjax',
    'sphinx.ext.ifconfig',
    'sphinx.ext.viewcode',
    'sphinx.ext.githubpages',
]

Initially, the index.rst file contains the following:


.. toctree::
   :maxdepth: 2
   :caption: Contents:

Create a new rst file called my_module.rst and add the following:


pysolrq package
===============

.. automodule:: pysolrq.solr
   :members:
   :undoc-members:
   :private-members:
   :special-members:

The sphinx.ext.autodoc Sphinx extension comes with automodule function that documents automatically from the Docstring of your given module (in this case, pysolrq.solr).

Now, edit your index.rst file to include your new rst file:


.. toctree::
   :maxdepth: 2
   :caption: Contents:

   my_module

3. Build your Sphinx project


sphinx-build -b html sourcedir builddir

where sourcedir is the directory where your source files are such as conf.py and index.rst; and buildir is where your Docstring documentation will be autogenerated in a nice looking html file. You can open the file in a browser and see how your Docstrings from your Python code were built into an html file.

In case you are getting an error because Sphinx is not able to find a Python module, you may need to add the parent directory of your module in the PYTHONPATH. You may do so by adding the following in your conf.py file:


import os
import sys
BASE_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), "../.."))
sys.path.append(BASE_DIR)

PUBLISHING
readthedocs.org hosts a lot of Sphinx docs already, and integrates well with projects' source control. It also features a powerful built-in search that exceeds the possibilities of Sphinx' JavaScript-based offline search. You only commit the source files of the Sphinx such as index.rst and and config.py and readthedocs will automatically build your Sphinx project and host it for you for free. Here is how it works:

1. Go to readthedocs.org and sign up for an account
2. Add you Sphinx github project
3. Enable readthedocs webhooks by going to the settings of your project

Now, Read the Docs will actually watch your GitHub project, and build, render and host your documents for you automatically.

Checkout this github project of mine. The API documentation at the bottom of the page is hosted on Read the Docs.

References:

Google-style Docstring
Numpy-style Docstring
sphinx.ext.autodoc
Restuctured Text and Sphinx Cheatsheet

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.