# Sphinx: Python Documentation Generator


Sphinx is a documentation generator that produces HTML, PDF, ePub, and other formats from source files written in [reStructuredText](https://docutils.sourceforge.io/rst.html) or [Markdown](https://myst-parser.readthedocs.io/). It powers the official [Python documentation](https://docs.python.org/) 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](https://pydevtools.com/handbook/reference/mkdocs.md).

## Key Features

* Reads reStructuredText (`.rst`) by default; reads Markdown (`.md`) through the [MyST](https://myst-parser.readthedocs.io/) 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](https://pydevtools.com/handbook/reference/furo.md) 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.

```python {filename="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`:

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

For an iterative authoring loop, use [sphinx-autobuild](https://pydevtools.com/handbook/reference/sphinx-autobuild.md) 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

* [Sphinx Documentation](https://www.sphinx-doc.org/)
* [GitHub Repository](https://github.com/sphinx-doc/sphinx)
* [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
* [Sphinx Extensions Survey](https://www.sphinx-doc.org/en/master/usage/extensions/index.html)
* [MyST: Markdown for Sphinx](https://myst-parser.readthedocs.io/)
* [How to Set Up Documentation for a Python Package with Sphinx or MkDocs](https://pydevtools.com/handbook/how-to/how-to-set-up-documentation-for-a-python-package.md) walks through scaffolding a Sphinx site inside a uv project
* [Read the Docs](https://pydevtools.com/handbook/reference/read-the-docs.md) is the standard hosting platform for Sphinx output
* [How to Build Read the Docs with uv](https://pydevtools.com/handbook/how-to/how-to-build-read-the-docs-with-uv.md) configures `.readthedocs.yaml` for uv-based builds