How to generate professional documentation with Sphinx?

#python #beginners #tutorial

Sphinx is a tool that makes it easy to generate professional documentation for software projects. This tool can generate beautiful documentation in HTML, PDF, epub and many other output formats. It was originally developed to create Python documentation. Later generalized to work with any project.

Sphinx uses reStructuredText as its markup language. It has a DocUtils suite that parses and translates Python Docstrings into markup language which is then used to generate HTML or PDF.

In this article, let’s see how to get started with Sphinx by going over high level steps involved in generating HTML documentation for a simple Python project documented using Docstring Convention.

Steps involved in generating HTML documentation:

Open any existing Python project.
Ensure project’s modules/classes/functions are documented using PEP 257 - Docstring Convention.
Install Sphinx tool using pip install sphinx in project’s virtual environment.
Create a folder called docs within the project folder. We are going to install Sphinx related artifacts in this folder.
Navigate to the docs folder and execute sphinx-quickstart command in the command line. When invoked, this utility asks simple questions about the project. Choosing default values should be sufficient.
Sphinx quick-start command generates files and folders which aids in generating HTML documentation.
Here is a high-level breakdown of artifacts generated using Sphinx quick-start command:
1. make utility - Utility used to generate html documentation
2. index.rst - Index page in reStructuredText format
3. conf.py - Mainly contains configuration information entered during sphinx-quickstart command
4. Other static HTML folders
To generate reStructuredText markup for the python package. Run sphinx-apidoc -o docs <package folder>/ command from project’s root folder. This will generate files with .rst extension in docs folder.
Before generating HTML documentation, below customization have to be done to conf.py

# OS path commands should be uncommented in conf.py file
# so that html utility could access the right project files to 
# generate documentation. 
import os
import sys
sys.path.insert(0, os.path.abspath('..'))

Also, update conf.py to include below extensions:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode'
]

To generate HTML documentation, run make html command from docs folder.
Once the above command is successful, generated html documentation can be found in the docs/html folder of the project.
Here is the generated HTML output taken from my sample project's environment: