Python Documentation: Generating HTML using Sphinx

Photo by Sigmund on Unsplash

This is part2 of the Python Documentation series. If you need help getting started with writing the documentation, you can take a look at part1

In this part, we will look at generating HTML files from the Python code docstrings. We will be using Sphinx for that. You can install sphinx via Pip

pip install sphinx

Sphinx typically works with ReStructured Text (.rst) files, but we can add support for Markdown(.md) files via m2r2

pip install m2r2

And we are done! Just kidding, but all that remains is updating few files and running few commands 😌

Note: Before generating docs, make sure that your codebase is a package (contains __init__.py at relevant locations)

Create a folder to store your docs and quick start the sphinx-setup:

mkdir docs && cd docs
sphinx-quickstart -q -p "<Project>" -a "<Author>" -v "<Version>"​

You should see something similar to the following inside your docs directory:

Sphinx-quickstart initial structure

Next, we need to update the conf.py (primary control / config file)

• Uncomment and Update the paths to make out python package visible

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

• Load sphinx extensions. You can read about the extensions in detail here

extensions = [
    'sphinx.ext.napoleon',      # Supports Google / Numpy docstring 
    'sphinx.ext.autodoc',       # Documentation from docstrings
    'sphinx.ext.doctest',       # Test snippets in documentation
    'sphinx.ext.todo',          # to-do syntax highlighting
    'sphinx.ext.ifconfig',      # Content based configuration
    'm2r2'                      # Markdown support 
]

• Add supported file extensions for documentation

source_suffix = [‘.rst’, ‘.md’]

You can customise your conf.py upto any extent (changing theme, adding support for latex, etc.

Now, we are ready to generate our documentation. The final build commands looks for .rst/.md files to generate html. Either you can manually write the files or use sphinx-apidoc to automatically do it for you.

sphinx-apidoc -f -o . ../​

To add rst / md files manually (readme, summary, etc), you can take help from Sphinx and ReStructured text syntax guides

You will see new .rst files, including a modules.rst inside your docs folder. We need to update this file inside our main index.rst

Welcome to Projects's documentation!
====================================

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

To add .md file, you will need to follow the syntax (instead of simply using .rst file name)

.. mdinclude:: ../README.md

Finally, we can build our rst / md files

make html​

If all goes well, you will have html files generated inside docs/_build/html/​

You can ignore some of the warnings, if they look irrelevant.

You can manually check the webpages by starting a python http server and redirect to the aforementioned directory in the browser (localhost:8000)

python –m http.server​

You should be able to see some fancy website containing the documentation of your module.