Python Developer Tooling Handbook – Documentation

Furo: Sphinx Documentation Theme

Tim Hopper — Wed, 29 Apr 2026 14:33:02 -0400

Furo is a Sphinx theme written by Pradyun Gedam. It is a clean, customisable replacement for Sphinx’s default alabaster theme, with built-in light and dark modes, a responsive layout, and a focused sidebar.

Note

How to Build Read the Docs with uv

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

If your docs already build on Read the Docs, you can now switch .readthedocs.yaml to native uv support instead of maintaining a hand-rolled build.jobs override. Read the Docs added this support on April 21, 2026. The two supported paths are uv sync with a docs dependency group, and uv pip install with a requirements file.

Define a docs dependency group

If your project already has a pyproject.toml, declare a dependency group for the documentation toolchain. Groups are the PEP 735 standard place to keep development-only dependencies out of what your users install:

How to Set Up Documentation for a Python Package with Sphinx or MkDocs

Tim Hopper — Fri, 15 May 2026 21:28:17 -0400

Sphinx and MkDocs are the two documentation generators most Python packages reach for. They cover the same job (turn Markdown or reStructuredText plus your docstrings into a static HTML site) but optimize for different writers. This guide picks one, scaffolds a docs site inside an existing uv project, and gets a build running locally.

Pick Sphinx or MkDocs

Two questions decide it for most projects.

What’s the dominant content type? API reference dominates in libraries like NumPy and Django, where most pages are autogenerated from docstrings. Sphinx was built for that workload and has the older and broader extension ecosystem around API reference work (intersphinx for cross-project links, sphinx-autodoc-typehints for signature rendering). MkDocs with mkdocstrings covers the API case competently, especially for Python-only projects. MkDocs is friendlier when the docs are prose-first and the API reference is one section among many tutorials and how-tos.

Material for MkDocs: Documentation Theme and Framework

Tim Hopper — Wed, 29 Apr 2026 14:33:02 -0400

Material for MkDocs is a theme and feature framework for MkDocs. Built by Martin Donath (squidfunk), it layers Material Design styling, client-side search, dark mode, code annotations, and a wide configuration surface on top of the base MkDocs build pipeline.

Note

MkDocs: Markdown Documentation for Python Projects

Tim Hopper — Fri, 01 May 2026 06:58:04 -0400

MkDocs is a static site generator that builds documentation websites from Markdown source files. A project’s structure, navigation, theme, and plugins are declared in a single mkdocs.yml file at the repo root.

Note

mkdocstrings: Autogenerate API Documentation in MkDocs

Tim Hopper — Wed, 29 Apr 2026 14:33:02 -0400

mkdocstrings is a MkDocs plugin that generates API documentation from source code and injects it directly into Markdown pages. The base plugin is language-agnostic; concrete language support ships as separate handler packages.

Note

Sphinx: Python Documentation Generator

Tim Hopper — Fri, 01 May 2026 06:58:04 -0400

Sphinx is a documentation generator that produces HTML, PDF, ePub, and other formats from source files written in reStructuredText or Markdown. It powers the official Python documentation and is the default documentation tool across most of the scientific Python ecosystem.

Note

sphinx-autobuild: Live Reload for Sphinx Documentation

Tim Hopper — Wed, 29 Apr 2026 14:33:02 -0400

sphinx-autobuild watches a Sphinx documentation source tree and rebuilds the HTML output every time a file changes. It also runs a small development web server and refreshes the browser automatically, replacing the edit-build-reload cycle with edit-and-look.

Note