Sphinx Documentation

Introduction

Sphinx is a powerful tool for generating intelligent and beautiful documentation. Originally developed for Python’s own documentation, Sphinx supports a variety of output formats and is highly extensible.

It is especially well-suited for documenting software projects, including Python-based codebases. It uses reStructuredText for content markup and integrates tightly with tools like Pygments and Docutils.

Key Features

  • Multiple output formats: HTML, PDF (via LaTeX), ePub, Texinfo, man pages, plain text, and more.

  • Cross-referencing: Semantic links for functions, classes, glossary terms, citations, etc.

  • Hierarchical structure: Easy document tree definition with parent/child navigation.

  • Indexing: Automatic general and module-specific indices.

  • Syntax highlighting: Via the Pygments highlighter.

  • Autodoc support: Pulls docstrings from Python modules automatically.

  • Extensions: Built-in and third-party extensions, many available via PyPI.

Installation

Install Sphinx as a development dependency using uv:

$ uv add --dev sphinx

Configuration

Initialize a Sphinx project using:

$ sphinx-quickstart -v $(uv version | awk '{print $2}') docs

This will generate the following structure:

docs
├── _build/
├── _static/
├── _templates/
├── conf.py
├── index.rst
├── make.bat
└── Makefile

Change the theme to Read the Docs for a better look:

$ uv add --dev sphinx-rtd-theme
$ uv remove --dev sphinx

Update conf.py:

html_theme = "sphinx_rtd_theme"

Rebuild the docs:

$ make -C docs clean
$ make -C docs html
$ brave-browser docs/_build/html/index.html

Enable autodoc and dynamic metadata in conf.py:

from pathlib import Path
import toml

def _get_project_meta():
    project_root = Path(__file__).resolve().parent.parent
    return toml.load(project_root / "pyproject.toml")["project"]

pkg_meta = _get_project_meta()
project = pkg_meta["name"]
copyright = "2025, Sunil Ghimire"
author = pkg_meta["authors"][0]["name"]
version = pkg_meta["version"]
release = version

Enable extensions:

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
]

Usage

Generate documentation from source files:

$ sphinx-apidoc -o docs/ src

Add the generated modules to index.rst:

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

   modules

Ignore generated .rst module files in Git:

# Ignore module docs
src*.rst

Rebuild documentation:

$ make -C docs clean
$ make -C docs html
$ chromium docs/_build/html/index.html

Test documentation build using tox by adding this to your tox.ini:

[tox]
envlist = ..., docs

[testenv:docs]
basepython = python
changedir = docs
deps =
    sphinx-rtd-theme
    toml
commands =
    sphinx-build -b html -d {envtmpdir}/doctrees . {envtmpdir}

Then run:

$ tox

Additional Resources

Useful extensions to consider:

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.coverage",
    "sphinx.ext.doctest",
    "sphinx.ext.githubpages",
    "sphinx.ext.napoleon",
    "sphinx.ext.todo",
    "sphinx.ext.viewcode",
]

To disable todo items from appearing in the output:

todo_include_todos = False

Better syntax highlighting:

pygments_style = "sphinx"

Next Step

Set up Continuous Integration with GitHub Actions to automatically test documentation builds.

Uninstall

Remove Sphinx-related packages:

$ uv remove --dev sphinx-rtd-theme