Skip to content

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

This guide sets up Sphinx or MkDocs inside an existing uv project. If you have not picked a generator, first compare Great Docs, Sphinx, Zensical, and MkDocs.

Important

Material for MkDocs is in maintenance mode. Its team moved feature development to Zensical, which reads existing mkdocs.yml files but does not support every MkDocs plugin. Keep the MkDocs production build while you compare representative pages with Zensical.

Add a docs dependency group

Whichever tool you pick, isolate the docs toolchain from your runtime dependencies. The PEP 735 dependency-group standard [dependency-groups] table is the place for it (see the dependency-groups explainer for the full model). Open pyproject.toml and add one of these:

pyproject.toml
[dependency-groups]
docs = [
    "sphinx>=8",
    "furo",
    "sphinx-autobuild",
]
pyproject.toml
[dependency-groups]
docs = [
    "mkdocs>=1.6",
    "mkdocs-material",
    "mkdocstrings[python]",
]

uv add --group docs sphinx furo sphinx-autobuild (or the MkDocs trio) writes the same thing.

Choose one generator and follow its setup section; these are separate configurations, not successive steps. The examples assume an installable package named greetlib with documented public objects. Substitute the package name if needed.

The rest of the guide assumes a src layout project that uv init --package produces. Both tools also work with flat layouts; the difference is which paths you point them at.

uv run executes the command inside the project’s virtual environment, ensuring all dependencies are installed first.

Set up Sphinx

sphinx-quickstart scaffolds the configuration. Run it from the repo root and point it at a new docs/ directory:

mkdir docs
uv run --group docs sphinx-quickstart docs --quiet --sep --makefile --no-batchfile --project='greetlib' --author='Your Name' --release='0.1.0' --language=en --extensions=sphinx.ext.autodoc,sphinx.ext.napoleon

--sep splits source from build. The result is docs/source/conf.py, docs/source/index.rst, and a Makefile. Edit docs/source/conf.py to switch the theme:

docs/source/conf.py
html_theme = "furo"

Furo adds built-in light and dark color schemes.

Replace docs/source/index.rst with a minimal page that pulls in your package:

docs/source/index.rst
greetlib
========

A tiny greeting library.

API reference
-------------

.. automodule:: greetlib
   :members:

The automodule directive imports greetlib, walks its public attributes, and renders each one’s docstring. sphinx.ext.napoleon lets you keep using Google- or NumPy-style docstrings instead of switching to native rST. Build the site:

$ uv run --group docs sphinx-build -b html docs/source docs/build/html
...
build succeeded.

Open docs/build/html/index.html in a browser to confirm the API section has rendered every public function. While editing, swap sphinx-build for sphinx-autobuild, which watches docs/source and your package source, rebuilds on change, and serves at http://127.0.0.1:8000:

uv run --group docs sphinx-autobuild docs/source docs/build/html --watch src

Without --watch src, edits to your package’s docstrings don’t trigger a rebuild because Sphinx considers them outside the documentation source tree.

Set up MkDocs

mkdocs new . scaffolds the same way, but in-place rather than under a docs/ subdirectory:

$ uv run --group docs mkdocs new .
INFO    -  Writing config file: ./mkdocs.yml
INFO    -  Writing initial docs: ./docs/index.md

You get an mkdocs.yml at the repo root and a docs/ directory with index.md. Replace mkdocs.yml with a configuration that picks the Material theme and wires up mkdocstrings to render the package:

mkdocs.yml
site_name: greetlib

theme:
  name: material

plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          paths: [src]

nav:
  - Home: index.md
  - API reference: api.md

paths: [src] tells the Python handler where to find your package on disk. With a flat layout, drop the key entirely or set it to [.].

Create docs/api.md with one line:

docs/api.md
::: greetlib

Each ::: directive is a placeholder for an auto-generated section. mkdocstrings walks greetlib, pulls the docstrings, and renders the API reference inline. Build the site:

$ uv run --group docs mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: ./site
INFO    -  Documentation built in 0.33 seconds

mkdocs serve runs a live-reload dev server at http://127.0.0.1:8000:

uv run --group docs mkdocs serve --watch src

The --watch src option includes the package source, so editing either a Markdown page or a docstring triggers a rebuild.

Host the result

Local builds are enough to review changes; long-lived URLs need a host. Read the Docs and GitHub Pages both publish static documentation sites.

Read the Docs builds on every push, serves versioned URLs (latest, stable, plus a URL per release tag), and runs both Sphinx and MkDocs. See How to Build Read the Docs with uv for its .readthedocs.yaml configuration.

GitHub Pages publishes the build output to <user>.github.io/<repo> from a branch or directly from a GitHub Actions workflow. MkDocs ships mkdocs gh-deploy, which pushes the built site/ to a gh-pages branch in one command. Sphinx has no built-in equivalent; use the peaceiris/actions-gh-pages action or push docs/build/html from a workflow.

Verify the rendered site

Before pointing a host at the repo, run the build cleanly one more time and skim the output:

  1. Confirm every public function and class your package exposes has rendered with a docstring. A blank entry is usually a missing or malformed docstring.
  2. Click through every link in the navigation. Sphinx prints a warning for unresolved references; MkDocs flags broken internal links if you set strict: true in mkdocs.yml.
Last updated on