Implementation:Spotify Luigi Sphinx Doc Configuration

Knowledge Sources	Spotify_Luigi
Domains	Documentation, Build_System
Last Updated	2026-02-10 08:00 GMT

Overview

Sphinx configuration file that controls the generation of Luigi's API documentation, including extension loading, theme configuration, and intersphinx mappings.

Description

The doc/conf.py file is the central Sphinx configuration for building Luigi's documentation. It is executed by Sphinx at build time and defines all settings that govern how documentation is generated from the Luigi source code. Key responsibilities include:

• Extension loading: Configures three Sphinx extensions -- sphinx.ext.autodoc for automatic API documentation from docstrings, sphinx.ext.viewcode for linking to highlighted source code, and sphinx.ext.autosummary for generating summary tables.
• Theme configuration: Uses the sphinx_rtd_theme (Read the Docs theme) for local builds. When building on readthedocs.org, the platform's default theme is used automatically.
• Autodoc settings: Sets autoclass_content = 'both' to append __init__ docstrings to class documentation, configures member ordering by source order (autodoc_member_order = 'bysource'), and defaults to showing both members and undocumented members.
• Version detection: Dynamically reads the installed Luigi package version using importlib.metadata.Distribution to populate version and release fields.
• Parameter representation: Patches luigi.parameter.Parameter.__repr__ at import time so that Parameter objects display their description, default values, and significance status in the generated documentation.
• Warning suppression: Monkey-patches sphinx.environment.BuildEnvironment.warn_node to suppress "nonlocal image URI" warnings that occur when referencing external images.
• ReadTheDocs integration: Detects the READTHEDOCS environment variable and auto-runs sphinx-apidoc to generate API stubs when building on the RTD platform.
• Multi-format output: Configures output targets for HTML, LaTeX, manual pages, and Texinfo formats.

Usage

This configuration file is used when building Luigi documentation via Sphinx. It is not importable as a Python module. To build the docs locally, run make html from the doc/ directory after installing sphinx_rtd_theme. The file is also automatically invoked by the Read the Docs build system when documentation is deployed online.

Code Reference

Source Location

• Repository: Spotify_Luigi
• File: doc/conf.py
• Lines: 1-346

Signature

# Key configuration variables (not a class/function -- this is a Sphinx config module)

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.autosummary',
]

autoclass_content = 'both'
needs_sphinx = '1.4.4'
autodoc_default_flags = ['members', 'undoc-members']
autodoc_member_order = 'bysource'
html_theme = 'sphinx_rtd_theme'  # when building locally
highlight_language = "python"
autodoc_mock_imports = ["mypy"]

Import

# N/A -- This is a Sphinx configuration file, not an importable Python module.
# It is executed by Sphinx via: sphinx-build or make html

I/O Contract

Inputs

Name	Type	Required	Description
Luigi source tree	Python source files	Yes	The Luigi package source code from which autodoc extracts docstrings
sphinx_rtd_theme	Python package	Yes (local)	The Read the Docs Sphinx theme, required for local doc builds
READTHEDOCS env var	Environment variable	No	Set to 'True' by the RTD platform to trigger automatic sphinx-apidoc generation
luigi (installed)	Python package	Yes	The installed Luigi package, used to extract version info and Parameter repr patching

Outputs

Name	Type	Description
HTML documentation	HTML files	Rendered HTML documentation in _build/html/
LaTeX documentation	LaTeX files	LaTeX output configured as Luigi.tex manual document
Man pages	Man page files	Unix manual pages generated from the index document
Texinfo documentation	Texinfo files	GNU Texinfo output for the Luigi project

Usage Examples

Basic Usage

# Build HTML documentation locally
cd doc/
pip install sphinx sphinx_rtd_theme
make html

# Or directly with sphinx-build
sphinx-build -b html . _build/html

Key Configuration Sections

# Extensions list (line 94-98)
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.autosummary',
]

# Version detection (line 121-125)
__version__ = Distribution.from_name('luigi').version
version = ".".join(__version__.split(".")[0:2])
release = __version__

# Theme configuration (line 173-180)
if not on_rtd:
    import sphinx_rtd_theme
    html_theme = 'sphinx_rtd_theme'
    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

# Autodoc settings (line 165-166)
autodoc_default_flags = ['members', 'undoc-members']
autodoc_member_order = 'bysource'

Related Pages

• Principle:Spotify_Luigi_Documentation_Build