liminfoSphinx Reference
Free reference guide: Sphinx Reference
About Sphinx Reference
The Sphinx Reference is a searchable quick-reference for Python documentation generation with Sphinx. It covers essential directives such as toctree for building table of contents hierarchies, note and warning for admonition boxes, code-block with syntax highlighting and line number options, image for embedding media, and literalinclude for pulling code directly from source files. Each entry includes the full directive syntax with all commonly used options.
This reference organizes Sphinx features into six categories: Directives, Roles, Config, Extensions, Themes, and autodoc. The Roles section covers cross-referencing with :ref:, :doc:, :func:, :class:, :meth:, and :term: for building interconnected documentation. The Config section provides conf.py settings including project metadata, extension loading, html_theme selection, language configuration for internationalization, and exclude_patterns for controlling build scope.
The Extensions and Themes sections help you extend Sphinx beyond basic documentation. Extensions covered include autodoc for auto-generating API docs from Python docstrings, napoleon for Google/NumPy docstring support, intersphinx for cross-project references, viewcode for source code links, and todo for tracking documentation tasks. The Themes section compares alabaster, Read the Docs, Furo, and Book themes with configuration examples. The autodoc section details autoclass, autofunction, automodule directives, and the sphinx-apidoc CLI tool.
Key Features
- Directive syntax for toctree, note, warning, code-block with linenos, image, and literalinclude
- Cross-reference roles including :ref:, :doc:, :func:, :class:, :meth:, and :term: with tilde shorthand
- conf.py configuration for project metadata, extensions list, html_theme, language, and exclude_patterns
- Extension setup for autodoc, napoleon (Google/NumPy docstrings), intersphinx, viewcode, and todo
- Theme comparison with configuration examples for alabaster, Read the Docs, Furo, and Book themes
- autodoc directives (autoclass, autofunction, automodule) with members, show-inheritance, and special-members options
- sphinx-apidoc CLI tool usage for generating API documentation scaffolding from Python packages
- autodoc_default_options configuration for consistent documentation generation across modules
Frequently Asked Questions
What is the toctree directive and how does maxdepth work?
The toctree directive creates a table of contents tree that links multiple .rst files into a hierarchical navigation structure. The :maxdepth: option controls how many heading levels deep the tree displays. For example, :maxdepth: 2 shows the document title and its first-level sections. The :caption: option adds a title above the tree. Documents are listed without file extensions, one per line, relative to the current file.
How do I use cross-references with :ref: vs :doc:?
:ref: links to a labeled location within any document using a target like ".. _my-label:" placed before a heading. :doc: links to an entire document by its file path. :ref: is preferred when linking to specific sections because it is robust against file moves. The tilde prefix (~) in roles like :func:`~module.function` displays only the short name. Both generate proper hyperlinks in HTML output.
What is the difference between autodoc and sphinx-apidoc?
autodoc is an extension that auto-generates documentation from Python docstrings using directives like .. automodule:: and .. autoclass::. sphinx-apidoc is a CLI tool that generates .rst stub files containing those autodoc directives for an entire Python package. Typically you run sphinx-apidoc once to create the file structure, then customize the generated .rst files. autodoc runs during every build to extract current docstrings.
How do I configure napoleon for Google-style docstrings?
Add "sphinx.ext.napoleon" to your extensions list in conf.py. Set napoleon_google_docstring = True for Google style or napoleon_numpy_docstring = True for NumPy style. Napoleon translates these human-readable formats into standard reStructuredText that autodoc can process. Key options include napoleon_include_init_with_doc for __init__ documentation and napoleon_use_param for parameter formatting.
What does intersphinx do and how do I set it up?
intersphinx enables cross-references to objects documented in other Sphinx projects. Configure it by adding "sphinx.ext.intersphinx" to extensions and defining intersphinx_mapping with project names and URLs. For example: intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}. Then use :func:`json.dumps` to link directly to Python stdlib docs. The None parameter tells Sphinx to download the objects.inv file automatically.
How do I choose between Furo, Read the Docs, and alabaster themes?
alabaster is Sphinx's default theme, minimal and clean but limited in features. Read the Docs (sphinx_rtd_theme) is the most popular, offering a sidebar navigation with deep nesting support and a familiar layout. Furo is a modern theme with dark mode toggle, clean typography, and better mobile responsiveness. Book theme (sphinx-book-theme) is ideal for tutorials and educational content with launch buttons for Jupyter notebooks.
How do I include source code from external files?
Use the literalinclude directive: ".. literalinclude:: path/to/file.py". Options include :language: for syntax highlighting, :lines: to specify line ranges (e.g., 1-10), :linenos: for line numbers, :emphasize-lines: to highlight specific lines, and :start-after: / :end-before: to extract code between markers. This keeps documentation in sync with actual source code without manual copying.
How do I set up Sphinx for multilingual documentation?
Set language = "ko" (or your target language) in conf.py. Configure locale_dirs = ["locale/"] and set gettext_compact = False. Run "sphinx-build -b gettext" to extract translatable strings, then use sphinx-intl to create .po files for translation. Each language builds as a separate output. For projects needing multiple language versions simultaneously, you can configure separate builds with different language settings.