Sphinx — Python Documentation Generator

Introduction

Sphinx is the standard documentation tool for the Python ecosystem and many other projects. It compiles reStructuredText or Markdown source files into HTML, PDF, ePub, and man pages with automatic cross-referencing, API documentation extraction, and a rich extension ecosystem.

What Sphinx Does

• Parses reStructuredText and MyST Markdown into a document tree
• Generates HTML, LaTeX/PDF, ePub, man pages, and plain text output
• Extracts API documentation from Python docstrings via the autodoc extension
• Builds cross-references between documents, modules, classes, and functions
• Supports themes, extensions, and custom directives for tailored output

Architecture Overview

Sphinx reads a configuration file (conf.py) and a master document that defines the table of contents tree. The parser converts source files into an internal doctree (based on docutils nodes). Builder classes then transform the doctree into the target output format. Extensions hook into events during parsing and building to add directives, roles, and transformations. The autodoc extension introspects live Python objects to generate reference pages.

Self-Hosting & Configuration

• Install via pip: pip install sphinx
• Run sphinx-quickstart to scaffold a project with conf.py and index.rst
• Add sphinx.ext.autodoc and sphinx.ext.napoleon for API documentation
• Install a theme like furo or sphinx-rtd-theme for polished HTML output
• Use sphinx-autobuild for live-reload during writing

Key Features

• First-class Python API documentation with autodoc and type-hint support
• Rich cross-referencing across documents, code objects, and external projects via intersphinx
• 1000+ community extensions for diagrams, notebooks, OpenAPI specs, and more
• Multiple output formats from a single source (HTML, PDF, ePub, man)
• Internationalization support with gettext-based translation workflows

Comparison with Similar Tools

• MkDocs — Markdown-native, simpler setup, but weaker cross-referencing and no autodoc
• Docusaurus — React-based, ideal for JavaScript projects; not Python-centric
• pdoc — minimal Python API docs generator; lacks narrative documentation support
• Doxygen — targets C/C++/Java; different markup language and ecosystem
• mdBook — Rust-oriented Markdown book builder; minimal plugin system

FAQ

Q: Can Sphinx use Markdown instead of reStructuredText? A: Yes. Install the MyST-Parser extension to write documentation in Markdown with full Sphinx directive support.

Q: How do I generate PDF output? A: Run make latexpdf. Sphinx produces LaTeX source and compiles it with pdflatex or xelatex.

Q: Does Sphinx work for non-Python projects? A: Yes. The Linux kernel, Blender, and many C/C++ projects use Sphinx. Language-specific domains are available for C, C++, JavaScript, and more.

Q: How do I host the output? A: Build the HTML and deploy to any static host. Read the Docs provides free hosting with automatic builds on git push.

Sources

• https://github.com/sphinx-doc/sphinx
• https://www.sphinx-doc.org/en/master/