Sphinx

Installation and Setup

Install from the Python Package Index (PyPI) into a virtual environment:

• Windows
• Linux + macOS

PS> py -m pip install sphinx

$ python -m pip install sphinx

Key Features

• Generates multiple output formats, such as HTML, ePub, LaTeX and PDF.
• Integrates with code via autodoc and autosummary to create API references from docstring.
• Supports rich cross references, indices, and automatic tables of contents for large projects.
• Offers a large extension ecosystem, including napoleon for Google or NumPy docstrings and intersphinx for links to external docs.
• Provides theming and templates with options like the Sphinx Book Theme and Read the Docs theme.

Usage

Create a new documentation skeleton:

$ sphinx-quickstart docs

Write content in reStructuredText files and update the toctree in index.rst:

.. toctree::
   :maxdepth: 1

   getting-started
   api/index

Document APIs from your package with autodoc:

.. automodule:: package.module
   :members:
   :undoc-members:

Build and preview the site:

$ sphinx-build -b html docs/ docs/_build/html

Enable common extensions:

extensions = [
    "sphinx.ext.autodoc",      # Pulls in API docs from docstrings
    "sphinx.ext.napoleon",     # Parses Google and NumPy style docstrings
    "sphinx.ext.intersphinx",  # Links to external docs
]
intersphinx_mapping = {"python": ("https://docs.python.org/3", {})}

To author in Markdown, install MyST-Parser and add it to extensions.

Related Resources

Course

Documenting Python Projects With Sphinx and Read the Docs

In this video series, you'll create project documentation from scratch using Sphinx, the de facto standard for Python. You'll also hook your code repository up to Read The Docs to automatically build and publish your code documentation.

intermediate best-practices