This is an automated email from the ASF dual-hosted git repository.
shahar1 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow-site.git
The following commit(s) were added to refs/heads/main by this push:
new 25a3472a2f Build Airflow docs with the theme from this checkout (#1691)
25a3472a2f is described below
commit 25a3472a2fb3804b2fd455fdd1b3e4f61b3135aa
Author: Shahar Epstein <[email protected]>
AuthorDate: Sat Oct 24 08:13:08 2026 +0300
Build Airflow docs with the theme from this checkout (#1691)
---
.github/workflows/build.yml | 23 +++++++++++++++++++
site.sh | 22 +++++++++++++++---
sphinx_airflow_theme/README.md | 51 +++++++++---------------------------------
3 files changed, 53 insertions(+), 43 deletions(-)
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 74e3aca056..4b50e4ffb0 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -253,6 +253,29 @@ jobs:
path: './sphinx_airflow_theme/demo/_build'
if-no-files-found: error
retention-days: 14
+ # Informational preview of real Airflow docs with this theme (needs
apache/airflow main to have
+ # `breeze build-docs --sphinx-airflow-theme-path`), so a failure does
not fail the PR.
+ - name: 🗂 Checkout apache/airflow
+ if: github.event_name == 'pull_request' &&
steps.check-theme.outputs.theme_changed == 'true'
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #
v7.0.1
+ with:
+ repository: apache/airflow
+ path: airflow
+ persist-credentials: false
+ - name: 📚 Build Airflow docs with this theme
+ id: airflow-docs
+ if: github.event_name == 'pull_request' &&
steps.check-theme.outputs.theme_changed == 'true'
+ continue-on-error: true
+ env:
+ AIRFLOW_REPO: ${{ github.workspace }}/airflow
+ run: ./site.sh build-airflow-docs
+ - name: 🚀 Upload Airflow docs built with this theme as artifact
+ if: steps.airflow-docs.outcome == 'success'
+ uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9
# v7.0.2
+ with:
+ name: airflow-docs-with-theme
+ path: './airflow/generated/_build/docs'
+ retention-days: 14
- name: 🚀 Create releases on GitHub
working-directory: sphinx_airflow_theme
env:
diff --git a/site.sh b/site.sh
index 8703f4c840..7ecbfb0ed7 100755
--- a/site.sh
+++ b/site.sh
@@ -35,6 +35,7 @@ These are the ${0} commands that can be used in various
situations:
preview-landing-pages Start the web server with preview of the landing
pages.
build-landing-pages Build the landing pages.
prepare-theme Copy required CSS/JS files from landing pages into
the docs theme.
+ build-airflow-docs Build Airflow docs with this theme (see
sphinx_airflow_theme/README.md).
install-node-deps Download all the Node dependencies (including Docsy
theme deps).
check-site-links Check to make sure that links are correct in the
website.
lint-css Lint CSS files.
@@ -66,9 +67,13 @@ function ensure_docsy_theme_deps_exists {
}
function ensure_that_website_is_build {
- log "Check if ${MY_DIR}/landing-pages/dist/index.html file exists"
- if [[ ! -f ${MY_DIR}/landing-pages/dist/index.html ]] ; then
- log "The website is not built. Start building."
+ local index=${MY_DIR}/landing-pages/dist/index.html
+ log "Check if ${index} exists and is newer than its SCSS/JS sources"
+ if [[ ! -f ${index} ]] || [[ -n $(find "${MY_DIR}/landing-pages/src" \
+ "${MY_DIR}/landing-pages/site/assets" \
+ "${MY_DIR}/landing-pages/site/themes/docsy/assets" \
+ -type f -newer "${index}" -print -quit) ]] ; then
+ log "The website is not built or out of date. Start building."
run_command "${MY_DIR}/landing-pages/" yarn run build
log "The website built."
fi
@@ -206,6 +211,15 @@ function prepare_theme {
echo "Successful copied required files"
}
+function build_airflow_docs {
+ AIRFLOW_REPO="$(cd "${AIRFLOW_REPO:-${MY_DIR}/../airflow}" && pwd)"
+ ensure_that_website_is_build
+ prepare_theme
+ # Breeze reads GITHUB_REPOSITORY, which is apache/airflow-site on GitHub
Actions.
+ run_command "${AIRFLOW_REPO}" uv run --locked --project
"${AIRFLOW_REPO}/dev/breeze" breeze build-docs \
+ --github-repository apache/airflow --sphinx-airflow-theme-path
"${MY_DIR}/sphinx_airflow_theme" "$@"
+}
+
if [[ "$#" -eq 0 ]]; then
echo "You must provide at least one command."
echo
@@ -243,6 +257,8 @@ elif [[ "${CMD}" == "check-site-links" ]]; then
elif [[ "${CMD}" == "prepare-theme" ]]; then
ensure_that_website_is_build
prepare_theme
+elif [[ "${CMD}" == "build-airflow-docs" ]]; then
+ build_airflow_docs "${@:-apache-airflow}"
elif [[ "${CMD}" == "lint-js" ]]; then
ensure_node_module_exists
if [[ "$#" -eq 0 ]]; then
diff --git a/sphinx_airflow_theme/README.md b/sphinx_airflow_theme/README.md
index 82c5bf5e8a..7eb27da7c0 100644
--- a/sphinx_airflow_theme/README.md
+++ b/sphinx_airflow_theme/README.md
@@ -66,49 +66,20 @@ In order to start working with the theme, please follow the
instructions below.
# Generate Airflow documentation with Sphinx theme changes
-If you made some modifications to Sphinx theme and want to generate Airflow
documentation to check the end results,
-please follow these steps:
+To see Airflow documentation rendered with the theme from this checkout, run
from the root of this
+repository (needs an [airflow](https://github.com/apache/airflow) checkout, uv
and Docker):
-1. In `airflow-site` repository, build Airflow website:
- ```shell script
- ./site.sh build-site
- ```
-
-2. Package the Sphinx theme in a `whl` file:
- ```shell script
- cd ./sphinx_airflow_theme
- python3 setup.py sdist bdist_wheel
- ```
-
-3. (Optional) Double-check your modifications to the Sphinx theme are in the
`whl` file:
- ```shell script
- pip install wheel
- wheel unpack ./sphinx_airflow_theme-0.0.11-py3-none-any.whl
- ```
-
-4. Copy the `whl` file to `files` directory in `airflow` repository:
- ```shell script
- cp ./sphinx_airflow_theme-0.0.11-py3-none-any.whl ${AIRFLOW_REPO}/files/
- ```
-
-5. In `airflow` repository, initiate a new breeze environment:
- ```shell script
- breeze
- ```
-
-6. In the breeze container, generate the documentation after installing the
theme:
- ```shell script
- pip install /files/sphinx_airflow_theme-0.0.11-py3-none-any.whl
--force-reinstall
- # Generate Airflow documentation only. If you need to generate the whole
documentation (all providers),
- # you can do it using
`/opt/airflow/scripts/in_container/run_docs_build.sh`. It takes longer to
execute.
- /opt/airflow/scripts/in_container/run_docs_build.sh --package-filter
apache-airflow
- ```
-
-7. Verify the documentation generated is correct and includes your
modifications. The documentation is generated in
-`docs/_build/docs/`. If you generated Airflow documentation only, you can
check the results in
-`docs/_build/docs/apache-airflow/latest/`.
+```shell script
+./site.sh build-airflow-docs
+```
+It runs `prepare-theme`, then `breeze build-docs --sphinx-airflow-theme-path`
in the Airflow checkout
+(`AIRFLOW_REPO`, default `../airflow`).
+Arguments are passed to `breeze build-docs` (default: `apache-airflow`). The
result is in
+`${AIRFLOW_REPO}/generated/_build/docs/`. If you used `./site.sh
preview-landing-pages`,
+run `./site.sh build-landing-pages` first.
+CI builds the same for pull requests that change the theme version, as the
`airflow-docs-with-theme` artifact.
# Install developer version
