Python Documentation: Generating HTML using Sphinx

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 docssphinx-quickstart -q -p "<Project>" -a "<Author>" -v "<Version>"

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

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.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store