You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airflow.apache.org by "shahar1 (via GitHub)" <gi...@apache.org> on 2026/10/18 12:34:50 UTC
[PR] Allow building docs with a local sphinx_airflow_theme checkout [airflow]
shahar1 opened a new pull request, #75001:
URL: https://github.com/apache/airflow/pull/75001
closes: #45576
<details><summary>AI Summary</summary>
Changes to the docs theme live in `airflow-site`, so checking them on real Airflow documentation meant building a wheel by hand and force-installing it inside a Breeze shell. This adds `--sphinx-airflow-theme-path` to `breeze build-docs`: the given `sphinx_airflow_theme` folder of an `airflow-site` checkout is mounted read-only into the docs container and installed there before the build, so neither checkout nor `uv.lock` changes. A folder without the theme's generated CSS/JS (`./site.sh prepare-theme`) is rejected before any Docker work, since it would otherwise build silently unstyled.
```bash
breeze build-docs apache-airflow --sphinx-airflow-theme-path ../airflow-site/sphinx_airflow_theme
```
Verified locally with Docker: a marker added to the local theme's `layout.html` appears in the built HTML and is absent without the option. The companion `airflow-site` change adds `./site.sh build-airflow-docs` and an informational CI preview on top of this option.
Not included: `--autobuild` with automatic rebuild when the mounted theme files change (raised on #70139); happy to follow up if wanted.
</details>
---
##### Was generative AI tooling used to co-author this PR?
- [X] Yes — Claude Code (Claude Opus 5.5)
Generated-by: Claude Code (Claude Opus 5.5) following [the guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#gen-ai-assisted-contributions)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Allow building docs with a local sphinx_airflow_theme checkout [airflow]
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #75001:
URL: https://github.com/apache/airflow/pull/75001#issuecomment-6380257544
### Backport successfully created: v3-4-test
Note: As of [Merging PRs targeted for Airflow 3.X](https://github.com/apache/airflow/blob/main/dev/README_AIRFLOW3_DEV.md#merging-prs-targeted-for-airflow-3x)
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.
In matter of doubt please ask in [#release-management](https://apache-airflow.slack.com/archives/C03G9H97MM2) Slack channel.
<table>
<tr>
<th>Status</th>
<th>Branch</th>
<th>Result</th>
</tr>
<tr>
<td>✅</td>
<td>v3-4-test</td>
<td><a href="https://github.com/apache/airflow/pull/75537"><img src="https://img.shields.io/badge/PR-75537-blue" alt="PR Link"></a></td>
</tr>
</table>
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Allow building docs with a local sphinx_airflow_theme checkout [airflow]
Posted by "kaxil (via GitHub)" <gi...@apache.org>.
kaxil commented on code in PR #75001:
URL: https://github.com/apache/airflow/pull/75001#discussion_r4360905621
##########
contributing-docs/11_documentation_building.rst:
##########
@@ -241,6 +241,17 @@ For example:
Will build ``fab`` provider documentation and clean build artifacts before.
+To try a change to the HTML theme (``sphinx_airflow_theme`` from the
+`airflow-site <https://github.com/apache/airflow-site>`_ repository) on real documentation, build with the
+theme folder of an ``airflow-site`` checkout instead of the published wheel:
+
+.. code-block:: bash
+
+ breeze build-docs apache-airflow --sphinx-airflow-theme-path ../airflow-site/sphinx_airflow_theme
+
+Run ``./site.sh prepare-theme`` in ``airflow-site`` first to generate the theme's CSS/JS. Breeze mounts the
Review Comment:
`prepare-theme` only runs `yarn run build` when `landing-pages/dist/index.html` is missing, then copies whatever is already in `dist` into `_gen`. So on a checkout that has been built once, editing the SCSS/JS and re-running `prepare-theme` copies the old bundle and the docs build shows the unchanged CSS. The README in apache/airflow-site#1691 already says to run `./site.sh build-landing-pages` first. Could this line, the `--sphinx-airflow-theme-path` help text and the `BadParameter` message say `./site.sh build-landing-pages && ./site.sh prepare-theme`?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Allow building docs with a local sphinx_airflow_theme checkout [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 merged PR #75001:
URL: https://github.com/apache/airflow/pull/75001
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Allow building docs with a local sphinx_airflow_theme checkout [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on PR #75001:
URL: https://github.com/apache/airflow/pull/75001#issuecomment-6334058208
Thanks for the reviews. The branch is rebased onto main, and the changes are in e721ac97e3..8cec2d98fa.
Review summary points, in order:
1. Read-only mount: no change. The theme builds with `flit_core` (`build-backend = "flit_core.buildapi"` in `airflow-site/sphinx_airflow_theme/pyproject.toml`), which does not write `*.egg-info` or `build/` into the source folder. It was run end to end with a real airflow-site checkout: a marker in `layout.html` showed up in the built HTML. The install was also checked against a read-only mount in the CI image.
2. `--no-deps` is replaced with `--reinstall-package sphinx-airflow-theme`. Only the theme is reinstalled, and a dependency that the theme adds is installed too.
3. `--sdk-docs-only` together with `--sphinx-airflow-theme-path` is now rejected with a usage error.
4. The `_gen` check is now a click callback that raises `click.BadParameter`. The help text says the path is the `sphinx_airflow_theme` sub-folder, not the airflow-site root.
5. `run_docs_build.sh` now installs the theme only when `SPHINX_AIRFLOW_THEME_PATH` is set.
6–7. Both build-docs test classes now share one fixture that stubs Docker with autospecced mocks and points `AIRFLOW_ROOT_PATH` to `tmp_path`. Before, the existing Python-version test deleted the real `generated/**/apis` folders.
8. The tests assert `exit_code == 0` before reading `call_args`. The rejection tests also check the error text, so they fail without the new option.
Follow-up issue for the auto-rebuild mode asked for on #70139: #75374.
---
Drafted-by: Claude Code (Opus 5.5) (no human review before posting)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Allow building docs with a local sphinx_airflow_theme checkout [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #75001:
URL: https://github.com/apache/airflow/pull/75001#discussion_r4345092956
##########
scripts/ci/docker-compose/mount-sphinx-airflow-theme.yml:
##########
@@ -0,0 +1,26 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+---
+services:
+ airflow:
+ # Added by `breeze build-docs --sphinx-airflow-theme-path`. The mount is read-only so the
+ # in-container install cannot leave root-owned build output in the airflow-site checkout.
+ volumes:
+ - type: bind
+ source: ${SPHINX_AIRFLOW_THEME_PATH}
+ target: /opt/sphinx_airflow_theme
+ read_only: true
Review Comment:
Thanks for checking it in the CI image. The mount stays read-only.
---
Drafted-by: Claude Code (Opus 5.5); reviewed by @shahar1 before posting
##########
scripts/in_container/run_docs_build.sh:
##########
@@ -21,6 +21,12 @@
git config --global --add safe.directory /opt/airflow
cd "${AIRFLOW_SOURCES}" || exit 1
+
+# Mounted by `breeze build-docs --sphinx-airflow-theme-path`.
+if [[ -d /opt/sphinx_airflow_theme ]]; then
+ uv pip install --no-deps --reinstall /opt/sphinx_airflow_theme
Review Comment:
Done in e721ac97e3: the script now runs `uv pip install --reinstall-package sphinx-airflow-theme /opt/sphinx_airflow_theme`.
---
Drafted-by: Claude Code (Opus 5.5); reviewed by @shahar1 before posting
##########
dev/breeze/tests/test_developer_commands.py:
##########
@@ -109,6 +109,53 @@ def test_python_option_is_rejected(self, runner):
assert "no such option" in result.output.lower()
+class TestBuildDocsSphinxAirflowTheme:
+ @pytest.fixture(autouse=True)
+ def _isolated_env(self, monkeypatch, tmp_path):
+ monkeypatch.setenv("SKIP_SAVING_CHOICES", "true")
+ for name in ("BREEZE_SDK", "DISTRIBUTIONS_LIST"):
+ monkeypatch.delenv(name, raising=False)
+ # The real _build_python_docs deletes generated/**/apis under AIRFLOW_ROOT_PATH.
+ monkeypatch.setattr("airflow_breeze.commands.developer_commands.AIRFLOW_ROOT_PATH", tmp_path)
+
+ @pytest.fixture
+ def docker_mocks(self):
+ with patch.multiple(
+ "airflow_breeze.commands.developer_commands",
+ perform_environment_checks=DEFAULT,
+ fix_ownership_using_docker=DEFAULT,
+ cleanup_python_generated_files=DEFAULT,
+ build_ci_image_if_needed=DEFAULT,
+ execute_command_in_shell=DEFAULT,
+ autospec=True,
+ ) as mocks:
+ mocks["execute_command_in_shell"].return_value.returncode = 0
+ yield mocks
+
+ @pytest.mark.parametrize("pass_option", [True, False])
+ def test_theme_path_is_passed_to_shell_params(
+ self, runner, docker_mocks, tmp_path, monkeypatch, pass_option
+ ):
+ (tmp_path / "theme" / "sphinx_airflow_theme" / "static" / "_gen").mkdir(parents=True)
+ monkeypatch.chdir(tmp_path)
+
+ runner.invoke(
+ build_docs,
+ ["--sphinx-airflow-theme-path", "theme"] if pass_option else [],
+ catch_exceptions=False,
+ )
+
+ shell_params = docker_mocks["execute_command_in_shell"].call_args.args[0]
+ assert shell_params.sphinx_airflow_theme_path == (str(tmp_path / "theme") if pass_option else "")
+
+ def test_theme_without_generated_assets_is_rejected(self, runner, docker_mocks, tmp_path):
Review Comment:
Done: the test now creates `sphinx_airflow_theme/` without `static/_gen` and also checks the error text, so it fails when only the package folder is checked.
---
Drafted-by: Claude Code (Opus 5.5); reviewed by @shahar1 before posting
##########
dev/breeze/src/airflow_breeze/commands/developer_commands.py:
##########
@@ -1052,11 +1060,21 @@ def build_docs(
distributions_list: str,
sdk: tuple[str, ...],
sdk_docs_only: bool,
+ sphinx_airflow_theme_path: str | None,
doc_packages: tuple[str, ...],
):
"""
Build documents.
"""
+ if (
Review Comment:
Done: `--sphinx-airflow-theme-path` together with `--sdk-docs-only` is now rejected with a usage error.
---
Drafted-by: Claude Code (Opus 5.5); reviewed by @shahar1 before posting
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Allow building docs with a local sphinx_airflow_theme checkout [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #75001:
URL: https://github.com/apache/airflow/pull/75001#discussion_r4365848556
##########
contributing-docs/11_documentation_building.rst:
##########
@@ -241,6 +241,17 @@ For example:
Will build ``fab`` provider documentation and clean build artifacts before.
+To try a change to the HTML theme (``sphinx_airflow_theme`` from the
+`airflow-site <https://github.com/apache/airflow-site>`_ repository) on real documentation, build with the
+theme folder of an ``airflow-site`` checkout instead of the published wheel:
+
+.. code-block:: bash
+
+ breeze build-docs apache-airflow --sphinx-airflow-theme-path ../airflow-site/sphinx_airflow_theme
+
+Run ``./site.sh prepare-theme`` in ``airflow-site`` first to generate the theme's CSS/JS. Breeze mounts the
Review Comment:
Done in 61758b63ff: the docs line, the `--sphinx-airflow-theme-path` help text and the `BadParameter` message now say `./site.sh build-landing-pages && ./site.sh prepare-theme`.
apache/airflow-site#1691 also fixes this on the `site.sh` side: `prepare-theme` and `build-airflow-docs` now rebuild the landing pages when the SCSS/JS sources are newer than the built bundle. Checked end to end with both branches: an SCSS edit in `airflow-site` showed up in the CSS of the `apache-airflow` docs built by `./site.sh build-airflow-docs`.
---
Drafted-by: Claude Code (Opus 5.5) (no human review before posting)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Allow building docs with a local sphinx_airflow_theme checkout [airflow]
Posted by "Andrushika (via GitHub)" <gi...@apache.org>.
Andrushika commented on code in PR #75001:
URL: https://github.com/apache/airflow/pull/75001#discussion_r4336290248
##########
scripts/ci/docker-compose/mount-sphinx-airflow-theme.yml:
##########
@@ -0,0 +1,26 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+---
+services:
+ airflow:
+ # Added by `breeze build-docs --sphinx-airflow-theme-path`. The mount is read-only so the
+ # in-container install cannot leave root-owned build output in the airflow-site checkout.
+ volumes:
+ - type: bind
+ source: ${SPHINX_AIRFLOW_THEME_PATH}
+ target: /opt/sphinx_airflow_theme
+ read_only: true
Review Comment:
I think the read-only mount is fine, since the theme builds with `flit_core` and does not write into the source tree. I ran the install against a read-only mount in the CI image and it worked.
##########
scripts/in_container/run_docs_build.sh:
##########
@@ -21,6 +21,12 @@
git config --global --add safe.directory /opt/airflow
cd "${AIRFLOW_SOURCES}" || exit 1
+
+# Mounted by `breeze build-docs --sphinx-airflow-theme-path`.
+if [[ -d /opt/sphinx_airflow_theme ]]; then
+ uv pip install --no-deps --reinstall /opt/sphinx_airflow_theme
Review Comment:
I think `--no-deps` is right here, because with `--reinstall` uv would otherwise reinstall all of Sphinx's dependencies. If theme deps are needed, `--reinstall-package sphinx-airflow-theme` without `--no-deps` only touches the theme.
##########
dev/breeze/tests/test_developer_commands.py:
##########
@@ -109,6 +109,53 @@ def test_python_option_is_rejected(self, runner):
assert "no such option" in result.output.lower()
+class TestBuildDocsSphinxAirflowTheme:
+ @pytest.fixture(autouse=True)
+ def _isolated_env(self, monkeypatch, tmp_path):
+ monkeypatch.setenv("SKIP_SAVING_CHOICES", "true")
+ for name in ("BREEZE_SDK", "DISTRIBUTIONS_LIST"):
+ monkeypatch.delenv(name, raising=False)
+ # The real _build_python_docs deletes generated/**/apis under AIRFLOW_ROOT_PATH.
+ monkeypatch.setattr("airflow_breeze.commands.developer_commands.AIRFLOW_ROOT_PATH", tmp_path)
+
+ @pytest.fixture
+ def docker_mocks(self):
+ with patch.multiple(
+ "airflow_breeze.commands.developer_commands",
+ perform_environment_checks=DEFAULT,
+ fix_ownership_using_docker=DEFAULT,
+ cleanup_python_generated_files=DEFAULT,
+ build_ci_image_if_needed=DEFAULT,
+ execute_command_in_shell=DEFAULT,
+ autospec=True,
+ ) as mocks:
+ mocks["execute_command_in_shell"].return_value.returncode = 0
+ yield mocks
+
+ @pytest.mark.parametrize("pass_option", [True, False])
+ def test_theme_path_is_passed_to_shell_params(
+ self, runner, docker_mocks, tmp_path, monkeypatch, pass_option
+ ):
+ (tmp_path / "theme" / "sphinx_airflow_theme" / "static" / "_gen").mkdir(parents=True)
+ monkeypatch.chdir(tmp_path)
+
+ runner.invoke(
+ build_docs,
+ ["--sphinx-airflow-theme-path", "theme"] if pass_option else [],
+ catch_exceptions=False,
+ )
+
+ shell_params = docker_mocks["execute_command_in_shell"].call_args.args[0]
+ assert shell_params.sphinx_airflow_theme_path == (str(tmp_path / "theme") if pass_option else "")
+
+ def test_theme_without_generated_assets_is_rejected(self, runner, docker_mocks, tmp_path):
Review Comment:
We might need `(tmp_path / "sphinx_airflow_theme").mkdir()` here. With an empty folder, the test also passes when the check only looks for the package folder.
##########
dev/breeze/src/airflow_breeze/commands/developer_commands.py:
##########
@@ -1052,11 +1060,21 @@ def build_docs(
distributions_list: str,
sdk: tuple[str, ...],
sdk_docs_only: bool,
+ sphinx_airflow_theme_path: str | None,
doc_packages: tuple[str, ...],
):
"""
Build documents.
"""
+ if (
Review Comment:
Nit: rejecting `--sdk-docs-only` with this option looks simpler, since the Java and TypeScript SDK docs don't use the Sphinx theme.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Allow building docs with a local sphinx_airflow_theme checkout [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #75001:
URL: https://github.com/apache/airflow/pull/75001#discussion_r4345092956
##########
scripts/ci/docker-compose/mount-sphinx-airflow-theme.yml:
##########
@@ -0,0 +1,26 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+---
+services:
+ airflow:
+ # Added by `breeze build-docs --sphinx-airflow-theme-path`. The mount is read-only so the
+ # in-container install cannot leave root-owned build output in the airflow-site checkout.
+ volumes:
+ - type: bind
+ source: ${SPHINX_AIRFLOW_THEME_PATH}
+ target: /opt/sphinx_airflow_theme
+ read_only: true
Review Comment:
Thanks for checking it in the CI image. The mount stays read-only.
---
Drafted-by: Claude Code (Opus 5.5) (no human review before posting)
##########
scripts/in_container/run_docs_build.sh:
##########
@@ -21,6 +21,12 @@
git config --global --add safe.directory /opt/airflow
cd "${AIRFLOW_SOURCES}" || exit 1
+
+# Mounted by `breeze build-docs --sphinx-airflow-theme-path`.
+if [[ -d /opt/sphinx_airflow_theme ]]; then
+ uv pip install --no-deps --reinstall /opt/sphinx_airflow_theme
Review Comment:
Done in e721ac97e3: the script now runs `uv pip install --reinstall-package sphinx-airflow-theme /opt/sphinx_airflow_theme`.
---
Drafted-by: Claude Code (Opus 5.5) (no human review before posting)
##########
dev/breeze/tests/test_developer_commands.py:
##########
@@ -109,6 +109,53 @@ def test_python_option_is_rejected(self, runner):
assert "no such option" in result.output.lower()
+class TestBuildDocsSphinxAirflowTheme:
+ @pytest.fixture(autouse=True)
+ def _isolated_env(self, monkeypatch, tmp_path):
+ monkeypatch.setenv("SKIP_SAVING_CHOICES", "true")
+ for name in ("BREEZE_SDK", "DISTRIBUTIONS_LIST"):
+ monkeypatch.delenv(name, raising=False)
+ # The real _build_python_docs deletes generated/**/apis under AIRFLOW_ROOT_PATH.
+ monkeypatch.setattr("airflow_breeze.commands.developer_commands.AIRFLOW_ROOT_PATH", tmp_path)
+
+ @pytest.fixture
+ def docker_mocks(self):
+ with patch.multiple(
+ "airflow_breeze.commands.developer_commands",
+ perform_environment_checks=DEFAULT,
+ fix_ownership_using_docker=DEFAULT,
+ cleanup_python_generated_files=DEFAULT,
+ build_ci_image_if_needed=DEFAULT,
+ execute_command_in_shell=DEFAULT,
+ autospec=True,
+ ) as mocks:
+ mocks["execute_command_in_shell"].return_value.returncode = 0
+ yield mocks
+
+ @pytest.mark.parametrize("pass_option", [True, False])
+ def test_theme_path_is_passed_to_shell_params(
+ self, runner, docker_mocks, tmp_path, monkeypatch, pass_option
+ ):
+ (tmp_path / "theme" / "sphinx_airflow_theme" / "static" / "_gen").mkdir(parents=True)
+ monkeypatch.chdir(tmp_path)
+
+ runner.invoke(
+ build_docs,
+ ["--sphinx-airflow-theme-path", "theme"] if pass_option else [],
+ catch_exceptions=False,
+ )
+
+ shell_params = docker_mocks["execute_command_in_shell"].call_args.args[0]
+ assert shell_params.sphinx_airflow_theme_path == (str(tmp_path / "theme") if pass_option else "")
+
+ def test_theme_without_generated_assets_is_rejected(self, runner, docker_mocks, tmp_path):
Review Comment:
Done: the test now creates `sphinx_airflow_theme/` without `static/_gen` and also checks the error text, so it fails when only the package folder is checked.
---
Drafted-by: Claude Code (Opus 5.5) (no human review before posting)
##########
dev/breeze/src/airflow_breeze/commands/developer_commands.py:
##########
@@ -1052,11 +1060,21 @@ def build_docs(
distributions_list: str,
sdk: tuple[str, ...],
sdk_docs_only: bool,
+ sphinx_airflow_theme_path: str | None,
doc_packages: tuple[str, ...],
):
"""
Build documents.
"""
+ if (
Review Comment:
Done: `--sphinx-airflow-theme-path` together with `--sdk-docs-only` is now rejected with a usage error.
---
Drafted-by: Claude Code (Opus 5.5) (no human review before posting)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Allow building docs with a local sphinx_airflow_theme checkout [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 commented on code in PR #75001:
URL: https://github.com/apache/airflow/pull/75001#discussion_r4365848556
##########
contributing-docs/11_documentation_building.rst:
##########
@@ -241,6 +241,17 @@ For example:
Will build ``fab`` provider documentation and clean build artifacts before.
+To try a change to the HTML theme (``sphinx_airflow_theme`` from the
+`airflow-site <https://github.com/apache/airflow-site>`_ repository) on real documentation, build with the
+theme folder of an ``airflow-site`` checkout instead of the published wheel:
+
+.. code-block:: bash
+
+ breeze build-docs apache-airflow --sphinx-airflow-theme-path ../airflow-site/sphinx_airflow_theme
+
+Run ``./site.sh prepare-theme`` in ``airflow-site`` first to generate the theme's CSS/JS. Breeze mounts the
Review Comment:
Done in 61758b63ff: the docs line, the `--sphinx-airflow-theme-path` help text and the `BadParameter` message now say `./site.sh build-landing-pages && ./site.sh prepare-theme`.
apache/airflow-site#1691 also fixes this on the `site.sh` side: `prepare-theme` and `build-airflow-docs` now rebuild the landing pages when the SCSS/JS sources are newer than the built bundle. Checked end to end with both branches: an SCSS edit in `airflow-site` showed up in the CSS of the `apache-airflow` docs built by `./site.sh build-airflow-docs`.
---
Drafted-by: Claude Code (Opus 5.5); reviewed by @shahar1 before posting
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org