Sphinx

Sphinx is the documentation generator behind the Python documentation and thousands of open source projects, from NumPy and Django to the Linux kernel. It builds HTML, PDF (through LaTeX), EPUB, and other formats from reStructuredText or Markdown sources, and its standout features are semantic cross-references — links to functions, classes, and sections that Sphinx resolves and checks — and API documentation generated from docstrings.

Sphinx has a steeper learning curve than Markdown-only tools, but it scales well to large reference documentation: every function can be linked from anywhere, references to other projects' docs resolve through intersphinx, and a strict build reports every broken reference. Combined with CI and Read the Docs, it gives Python projects versioned, verified documentation.

TL;DR

• A project has conf.py for configuration and a root document with a toctree defining the page hierarchy.
• Write in reStructuredText or Markdown via MyST-Parser, using directives (blocks) and roles (inline markup).
• Cross-reference objects and sections with roles like :py:func: and :ref:; link to other projects with intersphinx.
• Generate API references with autodoc and autosummary; support Google and NumPy docstrings with napoleon.
• Build with -W --keep-going -n to fail on warnings and broken references; test examples with the doctest builder and links with linkcheck.
• Host on Read the Docs or any static host.

Quick Example

A minimal docs/conf.py:

The root page with a toctree and an API reference:

Building with warnings as errors, then testing examples and links:

Core Concepts

Project Structure

Every page must appear in a toctree, or Sphinx warns that it is not included — a useful check against orphaned pages.

Markup: reStructuredText and MyST

reStructuredText (reST) is Sphinx's native markup, with directives for blocks (.. note::, .. code-block:: python, .. toctree::) and roles for inline semantics (:py:func:, :ref:, :doc:). MyST-Parser lets you write the same features in Markdown, using fenced directive blocks and {role} syntax, so teams can choose Markdown while keeping Sphinx's capabilities.

Cross-References

Unlike plain links, these are resolved at build time: rename a function and every reference to it warns. With nitpicky = True (or -n), even references in type annotations must resolve. Intersphinx extends this to other projects: a reference to the requests.Session class with the :py:class: role links into the Requests docs using their published object inventory.

API Documentation

• autodoc imports your modules and renders docstrings with directives such as autoclass, autofunction, and automodule.
• autosummary generates summary tables and per-object pages.
• napoleon parses Google- and NumPy-style docstrings.
• Type hints can be rendered in signatures or descriptions (autodoc_typehints), or with the sphinx-autodoc-typehints extension. See Python Type Hints.

Because autodoc imports your code, the docs build needs your package and its dependencies installed — or mocked with autodoc_mock_imports for heavy optional dependencies.

Quality Checks

Executable examples keep docs honest across releases; see Versioned Documentation and Executable Examples.

Themes and Hosting

Popular themes include Furo, sphinx-rtd-theme, PyData Sphinx Theme, and sphinx-book-theme. Read the Docs builds Sphinx projects from a .readthedocs.yaml file, with versions from branches and tags, pull request previews, and search:

Any static host works as well: the HTML builder outputs plain files.

Best Practices

Fail on Warnings From Day One

Turning on -W and nitpicky mode early is easy; cleaning hundreds of accumulated warnings later is not.

Use Semantic References, Not URLs

Link to objects and labeled sections with roles, so Sphinx checks them and keeps them correct when pages move.

Write Docstrings for Readers

Consistent docstring style (Google or NumPy with napoleon), parameter descriptions, and examples make autodoc output useful rather than a list of signatures.

Separate Guides From Reference

Combine generated API reference with hand-written tutorials and how-to guides; autodoc alone is not documentation. See API Documentation.

Common Mistakes

Plain URLs to Your Own Pages

Docs Build That Ignores Import Failures

Examples Never Tested

FAQ

What is Sphinx used for?

Building documentation — especially for Python projects — from reStructuredText or Markdown, with cross-references, API references generated from docstrings, and output to HTML, PDF, and other formats.

Can Sphinx use Markdown?

Yes. The MyST-Parser extension lets you write Sphinx documentation in Markdown, including directives and roles, and mix Markdown and reStructuredText in one project.

What is intersphinx?

A Sphinx extension that resolves cross-references to other projects' documentation using their published object inventories, so you can link directly to classes and functions in, for example, the Python standard library docs.

How do I generate API docs with Sphinx?

Enable autodoc (and optionally autosummary and napoleon), make your package importable in the docs build, and use directives such as automodule or autoclass to render docstrings.

Sphinx or MkDocs?

Sphinx excels at large reference documentation with checked cross-references and API docs; MkDocs is simpler and Markdown-first for guides and product documentation. See MkDocs.

Related Topics

• Docs as Code — Managing documentation like software
• MkDocs — A Markdown-first documentation site generator
• API Documentation — Writing useful API references
• Python Type Hints — Types rendered in API docs
• Python — The ecosystem Sphinx grew up in
• Technical Writing — Writing for developers and users

References

• Sphinx documentation
• sphinx.ext.autodoc (Sphinx documentation)
• sphinx.ext.intersphinx (Sphinx documentation)
• MyST-Parser documentation
• Configuration file v2 (Read the Docs documentation)