Sphinx

Sphinx is a documentation generator for Python projects that builds HTML and PDF documentation from structured docs and docstrings.

Installation and Setup

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

Windows PowerShell 
PS> py -m pip install sphinx
Shell 
$ 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:

Shell 
$ sphinx-quickstart docs

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

reStructuredText 
.. toctree::
   :maxdepth: 1

   getting-started
   api/index

Document APIs from your package with autodoc:

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

Build and preview the site:

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

Enable common extensions:

Python docs/conf.py 
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.