Implementation:Apache Airflow Core Docs Conf

Knowledge Sources	Apache_Airflow
Domains	Documentation, Build_System
Last Updated	2026-02-08 21:00 GMT

Overview

Sphinx documentation configuration for building the Apache Airflow core documentation, including autoapi generation, intersphinx cross-referencing, REST API docs via ReDoc, and Jinja template contexts for versioned content.

Description

The airflow-core/docs/conf.py file is a 386-line Python configuration module for the Sphinx documentation builder. It configures all aspects of how the airflow-core documentation is generated:

• Project metadata: Sets project = "apache-airflow" with version pulled from airflow.__version__.
• Extensions: Loads a rich set of Sphinx extensions:
  • Core: autoapi.extension, sphinx_jinja, sphinx.ext.graphviz, sphinxcontrib.httpdomain
  • ReDoc for REST API rendering via sphinxcontrib-redoc
  • Standard extensions from BASIC_SPHINX_EXTENSIONS and SPHINX_REDOC_EXTENSIONS
• AutoAPI: Configured to auto-generate API documentation from airflow-core/src/ and system tests, with selective inclusion of packages (hooks, operators, executors, sensors, timetables, triggers, etc.) and explicit exclusion of internal modules.
• Intersphinx: Cross-references to external projects including Google Cloud provider docs via get_intersphinx_mapping() and get_google_intersphinx_mapping().
• Jinja contexts: Provides template contexts for configuration docs (config_ctx), quick start guides (quick_start_ctx), and official download pages (official_download_page).
• ReDoc specs: Renders the Airflow REST API (v2) and Simple Auth Manager Token API using generated OpenAPI YAML specifications.
• Theme: Uses sphinx_airflow_theme with custom CSS, JavaScript for GitHub/Jira links, and redirects.

Usage

The documentation is built using Sphinx, typically via the project's build tooling:

# Build docs using uv (recommended)
uv run --group docs build-docs

# Build with auto-refresh server
uv run --group docs build-docs --autobuild

# Direct sphinx-build invocation
cd airflow-core/docs
sphinx-build -b html . _build/html

Code Reference

Source Location

• Repository: Apache_Airflow
• File: airflow-core/docs/conf.py
• Lines: 386

Signature

"""Configuration of building the Airflow-Core docs."""

from __future__ import annotations

import airflow

PACKAGE_NAME = "apache-airflow"
PACKAGE_VERSION = airflow.__version__

# Project metadata
project = PACKAGE_NAME
version = PACKAGE_VERSION
release = PACKAGE_VERSION

# Extensions
extensions = BASIC_SPHINX_EXTENSIONS
extensions.extend(SPHINX_REDOC_EXTENSIONS)
extensions.extend([
    "autoapi.extension",
    "sphinx_jinja",
    "sphinx.ext.graphviz",
    "sphinxcontrib.httpdomain",
    "extra_files_with_substitutions",
])

# Theme
html_theme = "sphinx_airflow_theme"
html_title = f"Airflow {PACKAGE_VERSION} Documentation"

# AutoAPI
autoapi_dirs = [AIRFLOW_CORE_SRC_PATH.as_posix(), SYSTEM_TESTS_DIR.as_posix()]
autoapi_root = "_api"
autoapi_keep_files = True

# Intersphinx
intersphinx_mapping = get_intersphinx_mapping()
intersphinx_mapping.update(get_google_intersphinx_mapping())

# ReDoc REST API specs
redoc = [
    {
        "name": "Airflow REST API",
        "page": "stable-rest-api-ref",
        "spec": main_openapi_path.as_posix(),
    },
    {
        "name": "Simple auth manager token API",
        "page": "core-concepts/auth-manager/simple/sam-token-api-ref",
        "spec": sam_openapi_path.as_posix(),
    },
]

# Jinja contexts for template rendering
jinja_contexts = {
    "config_ctx": {"configs": configs, "deprecated_options": deprecated_options},
    "quick_start_ctx": {"doc_root_url": f"https://airflow.apache.org/docs/apache-airflow/{PACKAGE_VERSION}/"},
    "official_download_page": {
        "airflow_version": PACKAGE_VERSION,
        "task_sdk_version": TASK_SDK_VERSION,
    },
}

def setup(sphinx):
    sphinx.connect("autoapi-skip-member", skip_util_classes_extension)

I/O Contract

Inputs

Name	Type	Required	Description
RST source files	.rst	Yes	ReStructuredText documentation source files in airflow-core/docs/
Python source files	.py	Yes	Python source code used by autoapi for API documentation generation
OpenAPI YAML specs	.yaml	Yes	Generated OpenAPI specs for REST API and auth manager API documentation
Configuration description	config.yml	Yes	Airflow configuration metadata used for config reference docs
Sphinx theme	sphinx_airflow_theme	Yes	Custom Airflow documentation theme package

Outputs

Name	Type	Description
HTML documentation	_build/html/	Complete built HTML documentation site
AutoAPI pages	_api/	Auto-generated API reference pages for Python modules
REST API reference	HTML via ReDoc	Interactive REST API documentation rendered from OpenAPI specs

Usage Examples

Building Documentation Locally

# Recommended approach using uv
uv run --group docs build-docs

# With auto-refresh for development
uv run --group docs build-docs --autobuild

Key Configuration Variables

Variable	Value	Description
project	"apache-airflow"	Package name used in documentation
html_theme	"sphinx_airflow_theme"	Custom Sphinx theme
autoapi_root	"_api"	Directory for auto-generated API pages
autoapi_keep_files	True	Retain generated files for debugging
viewcode_follow_imported_members	True	Follow re-exports in source view
graphviz_output_format	"svg"	SVG format for graph diagrams

Related Pages

• Environment:Apache_Airflow_Development_Contributor_Environment