Documenting and Publishing Your Python Code


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.

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

Numpy-style Docstring

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

    Extended description of function.

    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2
   return True


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


2. Edit, index.rst and add any rst file as needed
The above command generates 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 looks like:

extensions = [
    'sphinx.ext.napoleon',  # extension that can read numpy or Google style docstring

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

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:


3. Build your Sphinx project

sphinx-build -b html sourcedir builddir

where sourcedir is the directory where your source files are such as 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 file:

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

PUBLISHING 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 and readthedocs will automatically build your Sphinx project and host it for you for free. Here is how it works:

1. Go to 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.


Google-style Docstring
Numpy-style Docstring
Restuctured Text and Sphinx Cheatsheet