What is Sphinx in Python?

Sphinx is a documentation generator. It reads source files written in reStructuredText (its native markup) or Markdown (via the MyST extension) and produces HTML, PDF, ePub, manual pages, and other output formats. Sphinx is best known for powering the official CPython documentation, and is the default doc tool for most of the scientific Python ecosystem (NumPy, SciPy, scikit-learn, pandas).

What is the difference between Sphinx and MkDocs?

Sphinx writes reStructuredText by default and ships an extension ecosystem oriented around API reference work (autodoc, intersphinx, autodoc-typehints). MkDocs is Markdown-only and is generally simpler to set up for prose-first documentation. The choice usually comes down to two questions: is the project's content API-first (favors Sphinx) or prose-first (favors MkDocs), and are contributors comfortable with reStructuredText (Sphinx default) or do they want Markdown only (MkDocs).

What does Sphinx autodoc do?

`sphinx.ext.autodoc` is a built-in extension that imports a Python module and renders its docstrings as documentation. It walks the public attributes of a module, class, or function and emits a documentation page directly from the source. Combined with `sphinx.ext.napoleon`, autodoc reads Google-style and NumPy-style docstrings without requiring authors to switch to native reStructuredText field lists.

How do I install Sphinx?

Install Sphinx with `uv add --group docs sphinx` (or `pip install sphinx`) to add it to a `[dependency-groups]` docs group. Then run `sphinx-quickstart docs` to scaffold a documentation site, edit `docs/source/conf.py` to enable extensions, and run `sphinx-build -b html docs/source docs/build/html` to render the HTML.

Does Sphinx support Markdown?

Yes, via the [MyST](https://myst-parser.readthedocs.io/) extension. Install `myst-parser` and add it to the `extensions` list in `conf.py`, and Sphinx will accept `.md` files alongside `.rst` files. The surrounding ecosystem (autodoc directives, intersphinx references, third-party extensions) still assumes reStructuredText syntax for inline directives, so Markdown-first contributors mix MyST roles into their Markdown to access Sphinx features.

Sphinx: Python Documentation Generator

by Tim Hopper

Documentation

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 9.1.0 was released on December 31, 2025 and is licensed BSD-2-Clause. Install via uv add --group docs sphinx or pip install sphinx.

When to use Sphinx

Pick Sphinx when the documentation is API-first (most pages are autogenerated from docstrings), when contributors are comfortable with reStructuredText, or when the project benefits from the broader cross-reference and extension ecosystem (intersphinx for cross-project links, sphinx-autodoc-typehints for signature rendering). Sphinx is the established default for CPython, NumPy, SciPy, scikit-learn, pandas, Django, and Flask. For a comparison with the Markdown-first alternative, see the MkDocs reference.

Key Features

Reads reStructuredText (.rst) by default; reads Markdown (.md) through the MyST extension
Automatic API documentation from Python source via sphinx.ext.autodoc
Cross-project references via sphinx.ext.intersphinx (link from your docs to CPython, NumPy, requests, and any other Sphinx-built site)
Multiple output builders out of the box: HTML, LaTeX (for PDF), ePub, Texinfo, manual pages, JSON, plain text
Theme ecosystem: built-in alabaster, plus third-party themes like Furo and the Read the Docs theme
Extension API used by hundreds of third-party packages

Built-in Extensions

Sphinx ships with several extensions that most projects enable in conf.py:

Extension	Purpose
`sphinx.ext.autodoc`	Import a module and render its docstrings
`sphinx.ext.napoleon`	Parse Google-style and NumPy-style docstrings
`sphinx.ext.intersphinx`	Link to other Sphinx sites by reference
`sphinx.ext.viewcode`	Add a “[source]” link from each documented object to its source
`sphinx.ext.doctest`	Run interactive doctest snippets as part of the build
`sphinx.ext.todo`	Collect `.. todo::` directives into a project-wide list

Configuration

A Sphinx site lives in a docs directory with a conf.py file (Python configuration), a top-level index.rst (the table of contents), and one or more source files. sphinx-quickstart scaffolds the directory.

docs/source/conf.py

project = "mypackage"
extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "sphinx.ext.intersphinx",
]
html_theme = "furo"

Build the HTML output with sphinx-build:

sphinx-build -b html docs/source docs/build/html

For an iterative authoring loop, use sphinx-autobuild instead, which watches the source tree and refreshes the browser on change.

Pros

Long track record (first release 2008)
Largest extension ecosystem of any Python doc tool
Multiple output formats from a single source tree
Standard choice in scientific Python and CPython itself
Cross-references work across projects via intersphinx

Cons

reStructuredText has a steeper learning curve than Markdown for new contributors
Configuration via executable Python conf.py is more flexible but harder to reason about than a static YAML file
Default alabaster theme looks dated; most projects switch to Furo or the Read the Docs theme
MyST closes the Markdown gap but does not eliminate the reStructuredText assumptions in third-party extensions

Learn More

Last updated on April 29, 2026

setuptools sphinx-autobuild

Please submit corrections and feedback...