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

[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.

[potiuk]

Hmm:

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.

When I look at that - I think we should do locoal building of assets in airflow repo (it's really needed when you want to locally modiy the theme and see it "live" - that was the main motivation of the change. I do not think they should be pulled from wheel - it does not solve any issue to be honest.

[srchilukoori]

Hmm:

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.

When I look at that - I think we should do locoal building of assets in airflow repo (it's really needed when you want to locally modiy the theme and see it "live" - that was the main motivation of the change. I do not think they should be pulled from wheel - it does not solve any issue to be honest.

@potiuk Having the site files in this repo, would lead to code divergence between the site and the airflow repository. Are you planning to merge the airflow-site into this repository? The current state (in this PR) is keeping the airflow-site as SOT, and pulling new versions when there are updates to airflow-site.

[potiuk]

I really think that this is far too much to solve the issue. It does not solve the actual issue described - being able to quickly iterate n the theme changes while working on docs.

Looking at the current implementation, I think a better approach would be to handle the case differently:

1. checkout "airflow-site" repo locally somewhgere
2. Run breeze with --local-theme <path> to mount-bind the theme from checked-out airflow-site
3. Iterate and run doc build in breeze while haivng the theme mounted from "airflow-site" - including "dev" building the assets on the flight.

That would be far less intrusive - and would be an "easy" dev-env for docs - and it would solve the case where we want to be able to work on theme and see the result of it in versioned docs - while also (in airflow-site) build the docs for landing page and the website with the same theme.

Then the flow would be:

1. iterate locally on the change
   2)commit / merge the airflow-site changes and release them while site is built
2. commit the local changes once the new them is published by site build

I think that seem like closes to what the issue describes.