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:
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
def func(arg1, arg2): """Summary line. Extended description of function. Parameters ---------- 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 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)
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.