Docstrings - Sphinx Tutorial

The goal of this tutorial is to show you the basic principles of doctring comments in python, and semi-automatic documentation generation using Sphinx.

https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/#basic-example

Docstring

• Check the following links which present Python docstrings:
• PEP 256
• PEP 257
• You can use different documentation styles. Google or numpy are more common, but the reStructuredText is the standard version understood by the Sphinx program (documentation generator):
• Google Python Style
• Numpy Python Style
• reStructuredText Style
• Comment your code properly following the Numpy or the Google style.
• Open a python interpreter, import one function of your package, and call the help() function sending it your function as a parameter.

Install the libraries

• Check if Sphinx is installed by typing sphinx-build --version
• pip install sphinx
• pip install recommonmark
• pip install sphinxcontrib-napoleon (not necessary for recent versions of Sphinx)

Create a docs at the same level of your package

• mkdir docs
• cd docs

Run the sphinx-quickstart script

sphinx-quickstart

Answer the different question, you should specifically say yes to some of them:

> Separate source and build directories (y/n) [n]:
y
> Name prefix for templates and static dir [_]:
_
The project name will occur in several places in the built documentation.
> Project name: Project666
> Author name(s): bad dog
> Project release []: 0
For a list of supported codes, see
http://sphinx-doc.org/config.html#confval-language.
> Project language [en]:
The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
> Source file suffix [.rst]:
One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:
Indicate which of the following Sphinx extensions should be enabled:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: y
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: n
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y
> coverage: checks for documentation coverage (y/n) [n]: y
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: n
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: y> viewcode: include links to the source code of documented Python objects (y/n) [n]: y
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: y
> Create Makefile? (y/n) [y]: y
> Create Windows command file? (y/n) [y]: n

After this step the following folder and files will be created in the docs folder:

• build: (empty) The generated html documentation files will be placed here

• source:

  • _static: (empty) Files other than code (e.g., images) should be placed here
  • _templates: (empty)
  • conf.py: Python configuration file
  • index.rst: Documentation's main page

• Makefile: Make file to generate the html documentation page

Check the index.rst file

The toctree section defines the documentation's table of content. Below this section you should insert other .rst file names (but without their extension) for each section :

Contents:

.. toctree::
   :maxdepth: 2

   intro
   install
   useless section
   useless section 2

• Create a intro.rst file and incorporate it to the index.rst
• Check the reStructuredText style syntax
• If you have doubts check the creating a new Sphinx project page
• Add an image to intro.rst (put your imager in the _static folder)
• There is blank line between the list line containing the toctree parameters and the files that should be added

Add napoleon to the extensions list in conf.py

napoleon is a Sphinx extension that parses docstrings with NumPy and Google style, and converts them to the reStructuredText style before sending it to Sphinx. napoleon does not modify your source code docstrings directly.

Add recommonmark to the extesions list in conf.py to enable it: extensions = ['sphinx.ext.napoleon']

Enable recommonmark

recommonmark is a Sphinx extension that allows you to use Markdown and reStructuredText in the same Sphinx project.

Add recommonmark to the extensions list in conf.py to enable it: extensions = ['recommonmark']

Run the makefile

• Type make html to execute the Makefile
• Check the content of the build folder

Generate automatically the documentation

Sphinx can parse the docstrings within your code to generate a documentation for the project (with the autodoc option)

• Uncomment the following lines in the conf.py file, and add the relative path to the code (from the folder where conf.py is located):

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

• Execute the following command line: sphinx-apidoc -f -o source/ ../package/
• -f forces sphinx to erase the documents it created before building new documents
• -o <output folder> <python package relative path> specifies the output files location and the python package location
• Check the files in the source folder
• Modify the index.rst file to include the new files that were created by sphinx-apidoc.
• Clean the output files make clean
• Execute the Makefile make html
• Check the output

Add examples to the documentation

• Try to include examples of code to your documentation, using the appropriate reStructuredText syntax.
• Add examples to your docstrings and run the Makefile again.
• Add some math formulas to your docstrings

Documentation Theme

It is possible to customize the theme. Take a look to the available themes, and to their respective options, and customize it.

Some interesting tutorials

• tutorial in spanish
• tutorial in english
• reStructuredText