Python Code Documentation with Sphinx — Core Concepts

What Sphinx Does

Sphinx is a documentation generator originally built for Python’s own docs. It reads reStructuredText (reST) or Markdown files, combines them with docstrings extracted from Python source code, and outputs HTML, PDF, or ePub documentation.

Its killer feature is autodoc — an extension that imports your Python modules and automatically generates API reference pages from docstrings.

Getting Started

Installation

pip install sphinx sphinx-rtd-theme

Initialize a Docs Folder

cd your-project
sphinx-quickstart docs/

This creates a docs/ directory with:

• conf.py — Sphinx configuration
• index.rst — the documentation root page
• Makefile — build commands

Build the Docs

cd docs/
make html

Open docs/_build/html/index.html in a browser to see the result.

Autodoc: From Code to Docs

Autodoc imports your package and reads docstrings at build time. Enable it in conf.py:

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",  # supports Google/NumPy style docstrings
    "sphinx.ext.viewcode",  # adds source code links
]

Then reference modules in your reST files:

API Reference
=============

.. automodule:: my_package.client
   :members:
   :undoc-members:
   :show-inheritance:

Sphinx imports my_package.client, finds all classes and functions, reads their docstrings, and renders them as formatted documentation.

Napoleon: Friendly Docstring Styles

Raw reST docstrings are verbose. Napoleon lets you write Google-style or NumPy-style docstrings that are easier to read in source code:

Google style:

def fetch(url: str, timeout: int = 30) -> Response:
    """Fetch a URL and return the response.

    Args:
        url: The URL to fetch.
        timeout: Request timeout in seconds.

    Returns:
        A Response object with status and body.

    Raises:
        ConnectionError: If the server is unreachable.
    """

NumPy style:

def fetch(url, timeout=30):
    """Fetch a URL and return the response.

    Parameters
    ----------
    url : str
        The URL to fetch.
    timeout : int, optional
        Request timeout in seconds (default 30).

    Returns
    -------
    Response
        A Response object with status and body.
    """

Both are converted to proper reST by Napoleon before Sphinx processes them.

Cross-References

Sphinx’s strength is linking between documentation pages and API items:

See :func:`my_package.client.fetch` for details.

The :class:`~my_package.models.User` class handles authentication.

The ~ prefix shows only the last component (User instead of my_package.models.User), keeping text readable while maintaining full links.

Themes

The default Sphinx theme is functional but dated. Popular alternatives:

• sphinx-rtd-theme — the Read the Docs look, familiar to most Python developers
• Furo — clean, modern, good dark mode support
• PyData Sphinx Theme — used by NumPy, pandas, SciPy

# conf.py
html_theme = "furo"

Hosting on Read the Docs

Read the Docs builds and hosts Sphinx documentation for free (open-source projects):

1. Push your project to GitHub
2. Sign in at readthedocs.org and import your repo
3. Add a .readthedocs.yml:

version: 2
build:
  os: ubuntu-22.04
  tools:
    python: "3.12"
sphinx:
  configuration: docs/conf.py
python:
  install:
    - requirements: docs/requirements.txt

Every push to main triggers a rebuild. Pull requests get preview builds automatically.

Common Misconception

“Sphinx is only for big open-source projects.” Internal libraries and microservices benefit just as much. A Sphinx site for your team’s shared utilities prevents the “ask Sarah, she wrote that module” bottleneck. The setup takes 15 minutes; the time savings are permanent.

Sphinx vs MkDocs

MkDocs uses Markdown instead of reST and is simpler to set up. However, Sphinx has deeper Python integration (autodoc, type-aware cross-references) and a larger extension ecosystem. Choose MkDocs for narrative documentation, Sphinx for API-heavy projects.

The one thing to remember: Enable autodoc and Napoleon, point Sphinx at your package, and your docstrings become a searchable, cross-referenced documentation site with minimal extra effort.