Generate API HTML Docs with Sphinx: A Quick Step‑by‑Step Tutorial

Background

Need to generate HTML documentation from an API for frontend engineers.

Learning Sphinx

Sphinx is a Python‑based documentation generator originally created for Python language docs, but it can be used for any project, even to write entire books.

Installation

pip install sphinx

Markup Syntax

Sphinx uses reStructuredText, a lightweight markup language similar to Markdown. See the official reST guide.

Project Structure

# tree -L 1 .
├── bin
├── etc
├── ops
├── setup.py
└── example

Create docs directory

# mkdir docs
# tree -L 1 .
├── bin
├── docs
├── etc
├── ops
├── setup.py
└── example

Generate reST files from Python code

# sphinx-apidoc -F -o docs/ ops/api/contrib

Creating file doc/contrib.rst.
Creating file docs/conf.py.
Creating file docs/index.rst.
Creating file docs/Makefile.
Creating file docs/make.bat.

For detailed usage, refer to the sphinx‑apidoc documentation.

Install Read the Docs theme

# pip install sphinx_rtd_theme

Configure conf.py

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

Add project to Python path

import sys, os
sys.path.append(os.path.join(os.getcwd(), "../ops/api"))

Build HTML documentation

# cd docs
# mkdir html
# sphinx-build . html

See the sphinx‑build invocation guide for more options.

Customizing generated docs

Edit contrib.rst to include only selected classes and methods:

contrib.Domain module
-------------------

.. automodule:: contrib.Domain
    :undoc-members:

    .. autoclass:: domains
        :members: get, post, put, delete

The resulting documentation is shown below.