Add sphinx-airflow-theme as uv workspace member

[srchilukoori]

Summary

Vendors sphinx-airflow-theme as a uv workspace member (docs-theme/). Templates are committed; compiled assets and template updates are synced from the published wheel at build time via scripts/ci/fetch_theme_assets.py. __init__.py is owned locally for version management via upgrade_important_versions.py.

Closes: #45576

Changes

• docs-theme/ — vendored theme (templates, config, static JS); _gen/ gitignored
• scripts/ci/fetch_theme_assets.py — downloads wheel, extracts all theme files except __init__.py (version source of truth stays local)
• pyproject.toml / devel-common/pyproject.toml — workspace member + >=0.3.11 dep
• Dockerfile.ci / .github/workflows/airflow-distributions-tests.yml — fetch assets in CI
• scripts/ci/docker-compose/local.yml / .dockerignore / docker_command_utils.py — bind-mount wiring
• upgrade_important_versions.py — tracks theme version in __init__.py
• dev/breeze/tests/test_theme_workspace.py — retry test for fetch script

Why two fetch points?

Breeze bind-mounts docs-theme/ over the image path, masking baked content. Workflow fetches on host; Dockerfile covers non-mount scenarios.

Theme sync model

airflow-site is the source of truth. When a new theme version is published, upgrade_important_versions.py bumps __version__ in __init__.py, which triggers fetch_theme_assets.py to re-extract all theme files (templates + _gen/ assets) from the new wheel. No reverse sync, no local asset builds.

Was generative AI tooling used to co-author this PR?

• Yes

[potiuk]

How are you going to make sure it is going to be synchronized between airlfow-site and airflow repo ?

[potiuk]

Waiting for explantion of how the process shoudl work

[srchilukoori]

@potiuk following up on the request for review.

[potiuk]

Two specifics to fold into the process question above:

1. Version downgrade. This moves the theme from the previously-pinned 0.3.10 (old URL + uv.lock) to 0.3.9 — docs-theme/sphinx_airflow_theme/__init__.py sets __version__ = "0.3.9" and the dep is relaxed to >=0.3.9. Since fetch_theme_assets.py derives the wheel URL from __version__, the docs build would fetch the 0.3.9 assets, not 0.3.10. If 0.3.10 carried fixes that's a silent regression — please bump __version__ to 0.3.10 (and keep >=0.3.10) unless the downgrade is deliberate.

2. Description vs. diff. The PR body lists edits to selective_checks.py ("removed redundant ^docs-theme pattern") and .pre-commit-config.yaml ("removed _gen/ exclusions"), but neither file is in the diff. Were they dropped on a rebase? The .pre-commit-config.yaml change looks load-bearing now that _gen/ is untracked — if the old _gen/ exclusions remain while the dir is gone, please reconcile.

---

This review was drafted by an AI-assisted tool and confirmed by an Apache Airflow maintainer. The findings below are observations, not blockers; an Apache Airflow maintainer — a real person — will take the next look at the PR. If you think a finding is mis-applied, please reply on the PR and a maintainer will weigh in.

More on how Apache Airflow handles maintainer review: contributing-docs/05_pull_requests.rst.

---

Drafted-by: Claude Code (Opus 4.8); reviewed by @potiuk before posting

[srchilukoori]

Two specifics to fold into the process question above:

1. Version downgrade. This moves the theme from the previously-pinned 0.3.10 (old URL + uv.lock) to 0.3.9 — docs-theme/sphinx_airflow_theme/__init__.py sets __version__ = "0.3.9" and the dep is relaxed to >=0.3.9. Since fetch_theme_assets.py derives the wheel URL from __version__, the docs build would fetch the 0.3.9 assets, not 0.3.10. If 0.3.10 carried fixes that's a silent regression — please bump __version__ to 0.3.10 (and keep >=0.3.10) unless the downgrade is deliberate.

2. Description vs. diff. The PR body lists edits to selective_checks.py ("removed redundant ^docs-theme pattern") and .pre-commit-config.yaml ("removed _gen/ exclusions"), but neither file is in the diff. Were they dropped on a rebase? The .pre-commit-config.yaml change looks load-bearing now that _gen/ is untracked — if the old _gen/ exclusions remain while the dir is gone, please reconcile.

This review was drafted by an AI-assisted tool and confirmed by an Apache Airflow maintainer. The findings below are observations, not blockers; an Apache Airflow maintainer — a real person — will take the next look at the PR. If you think a finding is mis-applied, please reply on the PR and a maintainer will weigh in.
More on how Apache Airflow handles maintainer review: contributing-docs/05_pull_requests.rst.

Drafted-by: Claude Code (Opus 4.8); reviewed by @potiuk before posting

@potiuk Updated the version to 0.3.10, and it will be auto updated in future builds, once the PR is merged.

[potiuk]

Hmm - I think I have one more proposal to make "documentation editing" works equally well for "versioned docs" in airflow and "airflow-site" for all the webpage stuff.

We basically want to have two workflows:

1. Update the theme in "airflow-site" and build the site and see any asset changes reflected in the "airflow-site" docs

2. we build airflow docs locally in "airflow" repo - and changing "sphinx-airflow-theme" locallly and seeing it applied live on local doc server (including generating assets)

I think that should be possilbe by:

a) locally building (not fetching) the _gen files - when we always fetch them from whl file, we cannot easily iterate locally on thme

b) synchronizing - rather than pulling the "airflow-sphinx-theme" between "airflow" and "airflow-site" - that means two -way operations:

• airflow fetching the theme files from "airflow-site" (not -gen) when running "important uppgrade" and rebuilding _gen rather than fetching them
• ailrflow-site - fetching the "airflow" changes from v3-2-stable when it changes committing those to "airflow-site"

Do you thin kit's a good and workable approach @srchilukoori ? If so - can you also implement it and add documentaiton to the docs building explaining this process (i.e. what you need to do in order to modify themes when you work on ailrflow, and what happens when you do it for "airflow-site".

[srchilukoori]

Hmm - I think I have one more proposal to make "documentation editing" works equally well for "versioned docs" in airflow and "airflow-site" for all the webpage stuff.

We basically want to have two workflows:

1. Update the theme in "airflow-site" and build the site and see any asset changes reflected in the "airflow-site" docs
2. we build airflow docs locally in "airflow" repo - and changing "sphinx-airflow-theme" locallly and seeing it applied live on local doc server (including generating assets)

I think that should be possilbe by:

a) locally building (not fetching) the _gen files - when we always fetch them from whl file, we cannot easily iterate locally on thme

b) synchronizing - rather than pulling the "airflow-sphinx-theme" between "airflow" and "airflow-site" - that means two -way operations:

• airflow fetching the theme files from "airflow-site" (not -gen) when running "important uppgrade" and rebuilding _gen rather than fetching them
• ailrflow-site - fetching the "airflow" changes from v3-2-stable when it changes committing those to "airflow-site"

Do you thin kit's a good and workable approach @srchilukoori ? If so - can you also implement it and add documentaiton to the docs building explaining this process (i.e. what you need to do in order to modify themes when you work on ailrflow, and what happens when you do it for "airflow-site".

I added the theme files to the fetch_theme_assets.py, the version bump will pull all files (new + existing). Adding the local build and bi-directional sync will add more complexity, so I prefer to keep it to forward sync from airflow-site to airflow.

[potiuk]

Thanks for the update — the version concern from my last pass is resolved: it's now __version__ = "0.3.11" and the dependency has moved from the URL-pinned wheel to the workspace member (sphinx-airflow-theme>=0.3.11), so fetch_theme_assets.py no longer resolves a stale/older asset. Good.

One thing before this can move: the branch is currently conflicting with main (DIRTY), so please rebase onto latest main. The two failing checks (Latest Boto and Pendulum2 provider tests) are unrelated to a docs-theme change and look like stale-base fallout — a rebase should clear both. Once it's rebased and green, ping me for a full re-review of the workspace-member wiring.

Not approving in the meantime — purely the rebase, not the approach.

---

This review was drafted by an AI-assisted tool and confirmed by an Airflow maintainer. The findings below are observations, not blockers; an Airflow maintainer — a real person — will take the next look at the PR. If you think a finding is mis-applied, please reply on the PR and a maintainer will weigh in.

More on how Airflow handles maintainer review: contributing-docs/05_pull_requests.rst.

[srchilukoori]

Thanks for the update — the version concern from my last pass is resolved: it's now __version__ = "0.3.11" and the dependency has moved from the URL-pinned wheel to the workspace member (sphinx-airflow-theme>=0.3.11), so fetch_theme_assets.py no longer resolves a stale/older asset. Good.

One thing before this can move: the branch is currently conflicting with main (DIRTY), so please rebase onto latest main. The two failing checks (Latest Boto and Pendulum2 provider tests) are unrelated to a docs-theme change and look like stale-base fallout — a rebase should clear both. Once it's rebased and green, ping me for a full re-review of the workspace-member wiring.

Not approving in the meantime — purely the rebase, not the approach.

This review was drafted by an AI-assisted tool and confirmed by an Airflow maintainer. The findings below are observations, not blockers; an Airflow maintainer — a real person — will take the next look at the PR. If you think a finding is mis-applied, please reply on the PR and a maintainer will weigh in.
More on how Airflow handles maintainer review: contributing-docs/05_pull_requests.rst.

rebased the branch and resolved the conflicts. ci tests are running now.