Add an option to mount `airflow-site/sphinx_airflow_theme` when running CI locally

[shahar1]

Description

As of today, making changes in Airflow's site theme requires a lot of effort, as sphinx_airflow_theme is installed from PyPi:

airflow/hatch_build.py

Line 158 in 14f6622

"sphinx-airflow-theme>=0.0.12",

It doesn't happen often, but when we need to modify it for any reason (for example, as part of upgrading Sphinx version and related components - see this PR), we need to make a lot of workarounds to make it work.
Having the option to mount local airflow-site directory will make it way easier to test.

Use case/motivation

No response

Related issues

No response

Are you willing to submit a PR?

• Yes I am willing to submit a PR!

Code of Conduct

• I agree to follow this project's Code of Conduct

[potiuk]

As discussed on slack. One of the solutions is to add it our uv workspace in airflow and build it from there. I might want to take a stab with that one soon-ish.

[srchilukoori]

@shahar1 , @potiuk can I help with implementing this?

[potiuk]

@shahar1 , @potiuk can I help with implementing this?

Sure. Working, green mergable PR solving the issue after you've learned on your own how to do it is always good.

[srchilukoori]

@shahar1 , @potiuk can I help with implementing this?

Sure. Working, green mergable PR solving the issue after you've learned on your own how to do it is always good.

@potiuk I'm working on adding sphinx-airflow-theme as a uv workspace member per your and @shahar1's discussion. One structural question on the _gen/ directory before I open a PR.

The theme's static/_gen/ is 1.1MB of build artifacts — minified CSS/JS, vendored jQuery/Bootstrap/Popper, and woff2 fonts. It's 92% of the theme by size.

Two options for handling it:

A. Commit _gen/ as-is
Simple, uv sync → build docs works with zero extra steps. Tradeoff: binary build artifacts in git history permanently, and we'd need to re-vendor manually when upstream updates.

B. Gitignore _gen/, fetch from the published wheel at build time
Only templates (~100KB) in git. A script extracts _gen/ from the existing wheel on airflow.apache.org — same URL the current dependency already uses. Breeze build-docs would auto-fetch if _gen/ is missing. Tradeoff: one extra build step, though it's a one-time fetch cached per version.

I'm leaning toward B to keep build artifacts out of git. Either way, upgrade_important_versions.py can be adapted to handle version bumps. Any preference?

[potiuk]

And wha do YOU think? those two options look like generated by your agent - which is fine, I am using agents all the time. But I would be interested what you think? You are ultimately rsponsible for making the PR, so I think you have some opinion and can propose the PR, taking responsibility for the choice. Ideally maintainers should be involved in review when there is working, green PR where all the consequences of the choice made are hashed out, hard to say what will be there with just "dry" question without seeing working, green PR.