This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch improve-live-staging-approach-for-docs
in repository https://gitbox.apache.org/repos/asf/airflow.git
commit aaea7d3488e1c84503048efe76bc64f9a38ed858
Author: Jarek Potiuk <ja...@potiuk.com>
AuthorDate: Wed May 14 22:17:06 2025 -0400
Improve flow for live/staging doc publishing
There are a couple of improvements for live/staging doc publishing.
1) we use auto/live/staging rather than buckets in the drop-downs
2) auto selection of live/staging depending on the tag used to
produce the documentation
3) we use env variables to pass inputs/outputs to scripts - which
is good security practice
4) watermark changes are applied to documentation published to
staging site
---
.github/workflows/publish-docs-to-s3.yml | 58 ++++++++++++++-------
dev/add_watermark.py | 85 +++++++++++++++++++++++++++++++
dev/images/staging.png | Bin 0 -> 17612 bytes
3 files changed, 126 insertions(+), 17 deletions(-)
diff --git a/.github/workflows/publish-docs-to-s3.yml
b/.github/workflows/publish-docs-to-s3.yml
index 748a466cf8c..82f521e46e7 100644
--- a/.github/workflows/publish-docs-to-s3.yml
+++ b/.github/workflows/publish-docs-to-s3.yml
@@ -24,6 +24,15 @@ on: # yamllint disable-line rule:truthy
description: "The branch or tag to checkout for the docs publishing"
required: true
type: string
+ destination:
+ description: "The destination location in S3"
+ required: false
+ default: auto
+ type: choice
+ options:
+ - auto
+ - live
+ - staging
include-docs:
description: |
Space separated list of docs to build.
@@ -38,14 +47,6 @@ on: # yamllint disable-line rule:truthy
required: false
default: "no-docs-excluded"
type: string
- destination-location:
- description: "The destination location in S3, default is live site"
- required: false
- default: "s3://live-docs-airflow-apache-org/docs"
- type: choice
- options:
- - s3://live-docs-airflow-apache-org/docs
- - s3://staging-docs-airflow-apache-org/docs
env:
AIRFLOW_ROOT_PATH: "/home/runner/work/temp-airflow-repo-reference" #
checkout dir for referenced tag
@@ -62,9 +63,11 @@ jobs:
REF: ${{ inputs.ref }}
INCLUDE_DOCS: ${{ inputs.include-docs }}
EXCLUDE_DOCS: ${{ inputs.exclude-docs }}
- DESTINATION_LOCATION: ${{ inputs.destination-location }}
+ DESTINATION: ${{ inputs.destination }}
outputs:
include-docs: ${{ inputs.include-docs == 'all' && '' ||
inputs.include-docs }}
+ destination-location: ${{ steps.parameters.outputs.destination-location
}}
+ destination: ${{ steps.parameters.outputs.destination }}
if: contains(fromJSON('[
"ashb",
"eladkal",
@@ -78,13 +81,29 @@ jobs:
steps:
- name: "Input parameters summary"
shell: bash
+ id: parameters
run: |
echo "Input parameters summary"
echo "========================="
echo "Ref: '${REF}'"
echo "Included docs : '${INCLUDE_DOCS}'"
echo "Exclude docs: '${EXCLUDE_DOCS}'"
- echo "Destination location: '${DESTINATION_LOCATION}'"
+ echo "Destination: '${DESTINATION}'"
+ if [[ "${DESTINATION}" == "auto" ]]; then
+ if [[ "${REF}" =~ ^.*[0-9]*\.[0-9]*\.[0-9]*$ ]]; then
+ echo "${REF} looks like final release, using live destination"
+ DESTINATION="live"
+ else
+ echo "${REF} does not looks like final release, using staging
destination"
+ DESTINATION="staging"
+ fi
+ fi
+ echo "destination=${DESTINATION}" >> ${GITHUB_OUTPUT}
+ if [[ "${DESTINATION}" == "live" ]]; then
+ echo
"destination-location=s3://live-docs-airflow-apache-org/docs/" >>
${GITHUB_OUTPUT}
+ else
+ echo
"destination-location=s3://staging-docs-airflow-apache-org/docs/" >>
${GITHUB_OUTPUT}
+ fi
build-ci-images:
name: Build CI images
@@ -179,18 +198,18 @@ jobs:
uses: actions/checkout@v4
with:
persist-credentials: false
- - name: "Prepare breeze & CI image: 3.9"
- uses: ./.github/actions/prepare_breeze_and_image
- with:
- platform: "linux/amd64"
- python: 3.9
- use-uv: true
- name: "Checkout ${{ inputs.ref }}"
run: |
git clone https://github.com/apache/airflow.git
"${AIRFLOW_ROOT_PATH}"
cd "${AIRFLOW_ROOT_PATH}" && git checkout ${REF}
env:
REF: ${{ inputs.ref }}
+ - name: "Prepare breeze & CI image: 3.9"
+ uses: ./.github/actions/prepare_breeze_and_image
+ with:
+ platform: "linux/amd64"
+ python: 3.9
+ use-uv: true
- name: "Download docs prepared as artifacts"
uses: actions/download-artifact@v4
with:
@@ -220,6 +239,11 @@ jobs:
run: breeze release-management add-back-references docker-stack
- name: "Generate back references for helm-chart"
run: breeze release-management add-back-references helm-chart
+ - name: "Update watermarks"
+ run: >
+ uv run dev/add_watermark.py --pattern 'main.min.css'
+ --folder generated/_build/docs --image-directory images --url-prefix
/docs/images
+ if: needs.build-info.outputs.destination == 'staging'
- name: Install AWS CLI v2
run: |
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip"; -o
/tmp/awscliv2.zip
@@ -235,7 +259,7 @@ jobs:
aws-region: us-east-2
- name: "Syncing docs to S3"
env:
- DESTINATION_LOCATION: "${{ inputs.destination-location }}"
+ DESTINATION_LOCATION: "${{
needs.build-info.outputs.destination-location }}"
SOURCE_DIR_PATH: "/mnt/airflow-site/docs-archive/"
EXCLUDE_DOCS: "${{ inputs.exclude-docs }}"
run: |
diff --git a/dev/add_watermark.py b/dev/add_watermark.py
new file mode 100755
index 00000000000..152c5a83fbb
--- /dev/null
+++ b/dev/add_watermark.py
@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+# 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.
+#
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+# "rich>=14.0.0",
+# ]
+# ///
+from __future__ import annotations
+
+import argparse
+import shutil
+from pathlib import Path
+
+from rich.console import Console
+
+console = Console(width=200, color_system="standard")
+
+CSS_TO_ADD = """
+ body {
+ position: relative; /* Ensures the pseudo-element is positioned relative
to the body */
+ z-index: 0; /* Keeps the content above the pseudo-element */
+ }
+
+ body::before {
+ content: "";
+ position: fixed;
+ top: 0;
+ left: 0;
+ width: 100%;
+ height: 100%;
+ background: url(URL_PREFIX/staging.png) repeat center center fixed; /*
Sets the background image */
+ opacity: 0.2; /* Makes the watermark semi-transparent */
+ pointer-events: none; /* Ensures the watermark doesn't interfere with
user interactions */
+ z-index: -1; /* Places the pseudo-element behind all other elements */
+ }
+"""
+
+IMAGE_FILE = Path(__file__).parent / "images" / "staging.png"
+
+if __name__ == "__main__":
+ parser = argparse.ArgumentParser(description="Add watermark")
+ parser.add_argument("--folder", required=True, help="Folder to look for
css files for")
+ parser.add_argument("--pattern", required=True, help="Glob pattern to look
for")
+ parser.add_argument("--url-prefix", required=True, help="URL prefix to use
for the image")
+ parser.add_argument(
+ "--image-directory",
+ required=True,
+ help="Image directory where image should be written-relative to folder
path.",
+ )
+ args = parser.parse_args()
+
+ folder_path = Path(args.folder)
+ pattern = args.pattern
+ url_prefix = args.url_prefix
+ image_directory_path = Path(args.image_directory)
+
+ content_to_add = CSS_TO_ADD.replace("URL_PREFIX", url_prefix)
+
+ files = folder_path.rglob(pattern)
+ for file in files:
+ content = file.read_text()
+ if "watermark semi-transparent" not in content:
+ console.print(f"[bright_blue]Adding watermark to:[/] {file}")
+ content = content + content_to_add
+ file.write_text(content)
+ target_image_location = folder_path / image_directory_path
+ target_image_location.mkdir(parents=True, exist_ok=True)
+ shutil.copy(IMAGE_FILE, target_image_location / "staging.png")
diff --git a/dev/images/staging.png b/dev/images/staging.png
new file mode 100644
index 00000000000..a7cbaf306b0
Binary files /dev/null and b/dev/images/staging.png differ
