Add sphinx-airflow-theme as uv workspace member

.dockerignore

@@ -74,6 +74,7 @@
 !conf.py
 !docs
 !docker-stack-docs
+!docs-theme
 !providers-summary-docs
 
 # Avoid triggering context change on README change (new companies using Airflow)

.github/dependabot.yml

@@ -42,6 +42,19 @@ updates:
         patterns:
           - "*"
 
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    cooldown:
+      default-days: 4
+    schedule:
+      # Check for updates to GitHub Actions every week
+      interval: "weekly"
+    target-branch: v2-11-test
+    groups:
+      github-actions-updates:
+        patterns:
+          - "*"
+
   - package-ecosystem: pip
     cooldown:
       default-days: 4
@@ -247,6 +260,39 @@ updates:
       - dependency-name: "*"
         update-types: ["version-update:semver-major"]
 
+  # Repeat dependency updates on 2.11 branch as well
+  - package-ecosystem: pip
+    cooldown:
+      default-days: 4
+    directories:
+      - /clients/python
+      - /dev/breeze
+      - /docker_tests
+      - /
+    schedule:
+      interval: "weekly"
+    target-branch: v2-11-test
+    groups:
+      pip-dependency-updates:
+        patterns:
+          - "*"
+
+  - package-ecosystem: npm
+    cooldown:
+      default-days: 4
+    directories:
+      - /airflow/www/
+    schedule:
+      interval: "weekly"
+    target-branch: v2-11-test
+    groups:
+      legacy-ui-package-updates:
+        patterns:
+          - "*"
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major"]
+
   - package-ecosystem: "uv"
     cooldown:
       default-days: 4

.github/workflows/airflow-distributions-tests.yml

@@ -104,6 +104,11 @@ jobs:
       - name: "Install Breeze"
         uses: ./.github/actions/breeze
         if: ${{ inputs.use-local-venv == 'true' }}
+      # `_gen/` is gitignored and bind-mounted from host into the container, so
+      # baking it into the image is masked at runtime. Fetch on host instead.
+      - name: "Fetch sphinx-airflow-theme static assets"
+        shell: bash
+        run: python scripts/ci/fetch_theme_assets.py
       - name: "Cleanup dist files"
         run: rm -fv ./dist/*
         if: ${{ matrix.python-version == inputs.default-python-version }}

.github/workflows/ci-image-checks.yml

@@ -205,6 +205,11 @@ jobs:
           python: "${{ inputs.default-python-version }}"
           use-uv: ${{ inputs.use-uv }}
           make-mnt-writeable-and-cleanup: true
+      # `_gen/` is gitignored and bind-mounted from host into the container, so
+      # baking it into the image is masked at runtime. Fetch on host instead.
+      - name: "Fetch sphinx-airflow-theme static assets"
+        shell: bash
+        run: python scripts/ci/fetch_theme_assets.py
       - name: "Restore docs inventory cache"
         uses: apache/infrastructure-actions/stash/restore@49df447b39b18354895520e0a63731b7cad7cbec
         with:

.github/workflows/publish-docs-to-s3.yml

@@ -315,6 +315,11 @@ jobs:
           --build-arg VERSION_SUFFIX_FOR_PYPI=dev0
           -t "ghcr.io/apache/airflow/main/ci/python${PYTHON_MAJOR_MINOR_VERSION}:latest" --target main .
           -f Dockerfile.ci --platform linux/amd64
+      # `_gen/` is gitignored and bind-mounted from host into the container, so
+      # baking it into the image is masked at runtime. Fetch on host instead.
+      - name: "Fetch sphinx-airflow-theme static assets"
+        shell: bash
+        run: python scripts/ci/fetch_theme_assets.py
       - name: "Restore docs inventory cache"
         uses: apache/infrastructure-actions/stash/restore@49df447b39b18354895520e0a63731b7cad7cbec
         with:

Dockerfile.ci

@@ -1936,6 +1936,8 @@ RUN --mount=type=cache,id=ci-$TARGETARCH-$DEPENDENCY_CACHE_EPOCH,target=/root/.c
     bash /scripts/docker/install_additional_dependencies.sh; \
     fi
 
+RUN python "${AIRFLOW_SOURCES}/scripts/ci/fetch_theme_assets.py"
+
 COPY --from=scripts entrypoint_ci.sh /entrypoint
 COPY --from=scripts entrypoint_exec.sh /entrypoint-exec
 RUN chmod a+x /entrypoint /entrypoint-exec

dev/breeze/src/airflow_breeze/utils/docker_command_utils.py

@@ -99,6 +99,7 @@
     ("docker-stack-docs", "/opt/airflow/docker-stack-docs"),
     ("docker-tests", "/opt/airflow/docker-tests"),
     ("docs", "/opt/airflow/docs"),
+    ("docs-theme", "/opt/airflow/docs-theme"),
     ("generated", "/opt/airflow/generated"),
     ("go-sdk", "/opt/airflow/go-sdk"),
     ("java-sdk", "/opt/airflow/java-sdk"),

dev/breeze/tests/test_theme_workspace.py

@@ -0,0 +1,38 @@
+# 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.
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from unittest import mock
+from urllib.error import URLError
+
+import pytest
+
+AIRFLOW_ROOT = Path(__file__).resolve().parents[3]
+sys.path.insert(0, str(AIRFLOW_ROOT / "scripts" / "ci"))
+import fetch_theme_assets  # noqa: E402
+
+
+@mock.patch("fetch_theme_assets.time.sleep")
+@mock.patch("fetch_theme_assets.urlopen")
+def test_retries_on_transient_failure(mock_urlopen, mock_sleep):
+    mock_urlopen.side_effect = [URLError("timeout"), URLError("reset"), URLError("refused")]
+    with pytest.raises(SystemExit, match="1"):
+        fetch_theme_assets.fetch_and_extract("0.0.1")
+    assert mock_urlopen.call_count == 3
+    assert mock_sleep.call_count == 2

devel-common/pyproject.toml

@@ -80,7 +80,7 @@ dependencies = [
     "docutils>=0.21",
     "pagefind>=1.5.0",
     "pagefind-bin>=1.5.0",
-    "sphinx-airflow-theme@https://airflow.apache.org/sphinx-airflow-theme/sphinx_airflow_theme-0.3.11-py3-none-any.whl",
+    "sphinx-airflow-theme>=0.3.11",
     "sphinx-argparse>=0.4.0",
     "sphinx-autoapi>=3.8.0",
     "sphinx-autobuild>=2024.10.2",

docs-theme/.gitignore

@@ -0,0 +1,2 @@
+*.iml
+sphinx_airflow_theme/static/_gen/

docs-theme/pyproject.toml

@@ -0,0 +1,44 @@
+# 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.
+
+[build-system]
+requires = ["flit_core==3.12.0"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "sphinx_airflow_theme"
+description = "Airflow theme for Sphinx"
+license = {text = "Apache License 2.0"}
+authors = [
+    {name = "Apache Software Foundation", email = "dev@airflow.apache.org"}
+]
+dynamic = ["version"]
+dependencies = [
+    "sphinx>=7"
+]
+requires-python = ">=3.9"
+
+[project.entry-points."sphinx.html_themes"]
+sphinx_airflow_theme = "sphinx_airflow_theme"
+
+[tool.flit.module]
+name = "sphinx_airflow_theme"
+
+[tool.flit.sdist]
+include = [
+    "sphinx_airflow_theme/**",
+]

docs-theme/sphinx_airflow_theme/__init__.py

@@ -0,0 +1,56 @@
+# 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.
+
+from __future__ import annotations
+
+from os import path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+__version__ = "0.3.11"
+
+_THEME_DIR = path.abspath(path.dirname(__file__))
+_GEN_DIR = path.join(_THEME_DIR, "static", "_gen")
+
+
+def get_html_theme_path():
+    """Return list of HTML theme paths."""
+    return path.abspath(path.dirname(_THEME_DIR))
+
+
+def setup_my_func(app, config):
+    config.html_theme_options.setdefault(
+        "navbar_links",
+        [
+            {"href": "/index.html", "text": "Documentation"},
+            {"href": "/registry/", "text": "Registry"},
+        ],
+    )
+
+
+def setup(app: Sphinx):
+    if not path.isdir(_GEN_DIR):
+        raise FileNotFoundError(
+            f"Theme static assets not found at {_GEN_DIR}. Run: python scripts/ci/fetch_theme_assets.py"
+        )
+    app.add_html_theme("sphinx_airflow_theme", _THEME_DIR)
+    app.add_css_file("_gen/css/main-custom.min.css")
+    app.add_js_file("js/globaltoc.js")
+    app.connect("config-inited", setup_my_func)
+    return {"version": __version__, "parallel_read_safe": True, "parallel_write_safe": True}

docs-theme/sphinx_airflow_theme/breadcrumbs.html

@@ -0,0 +1,41 @@
+{#
+ 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.
+#}
+
+{% if meta is defined and meta is not none %}
+    {% set check_meta = True %}
+{% else %}
+    {% set check_meta = False %}
+{% endif %}
+
+{% if check_meta and 'github_url' in meta %}
+    {% set display_github = True %}
+{% endif %}
+
+<div role="navigation" aria-label="breadcrumbs navigation" class="d-none d-md-block d-print-none">
+
+    <ul class="breadcrumb">
+        {% block breadcrumbs %}
+            <li class="breadcrumb-item"><a href="{{ pathto(master_doc) }}" class="icon icon-home"> {{ _('Home') }}</a></li>
+            {% for doc in parents %}
+                <li class="breadcrumb-item"><a href="{{ doc.link|e }}"> {{ doc.title }}</a></li>
+            {% endfor %}
+            <li class="breadcrumb-item"><a href="{{ pagename.split('/')[-1] }}{{ file_suffix }}"> {{ title }}</a></li>
+        {% endblock %}
+    </ul>
+</div>