From 8db13b936830d5591a2fa646c2326e9ec277c821 Mon Sep 17 00:00:00 2001 From: Alexander Erben Date: Wed, 22 Apr 2026 20:15:39 +0200 Subject: [PATCH] feat(docs): introduce versioned documentation for v5.x releases MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Build archived docs for v5.0–v5.3 alongside the latest docs and deploy them as subdirectories under GitHub Pages. A version selector dropdown lets readers switch between releases. Signed-off-by: Alexander Erben --- .github/workflows/hugo.yaml | 117 ++++++++++++++++-- .../dependent-resources.md | 4 +- .../workflows.md | 8 +- .../en/docs/documentation/reconciler.md | 2 +- docs/content/en/docs/faq/_index.md | 2 +- .../en/docs/migration/v3-1-migration.md | 2 +- .../en/docs/migration/v4-4-migration.md | 2 +- .../en/docs/migration/v4-5-migration.md | 2 +- docs/hugo.toml | 9 +- 9 files changed, 128 insertions(+), 20 deletions(-) diff --git a/.github/workflows/hugo.yaml b/.github/workflows/hugo.yaml index 74f97eb4a8..3734706f77 100644 --- a/.github/workflows/hugo.yaml +++ b/.github/workflows/hugo.yaml @@ -1,4 +1,4 @@ -# Sample workflow for building and deploying a Hugo site to GitHub Pages +# Workflow for building and deploying a versioned Hugo site to GitHub Pages name: Deploy Hugo site to Pages on: @@ -59,14 +59,46 @@ jobs: uses: actions/configure-pages@v6 - name: Install Node.js dependencies working-directory: ./docs - run: | - [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true - npm install -D autoprefixer - npm install -D postcss-cli - npm install -D postcss - - name: Build with Hugo + run: | + if [[ -f package-lock.json || -f npm-shrinkwrap.json ]]; then + npm ci + else + npm install --no-save autoprefixer postcss-cli postcss + fi + - name: Generate version dropdown + run: | + BASE_URL="${{ steps.pages.outputs.base_url }}" + BASE_PATH="$(echo "${BASE_URL}" | sed 's|https\?://[^/]*||')" + + # Discover v5.x releases from git tags automatically. + VERSIONS=() + for minor in $(git tag --list 'v5.*.*' --sort=-version:refname \ + | grep -E '^v5\.[0-9]+\.[0-9]+$' \ + | sed 's/\.[0-9]*$//' | sort -Vru); do + latest=$(git tag --list "${minor}.*" --sort=-version:refname \ + | grep -E '^v5\.[0-9]+\.[0-9]+$' | head -1) + VERSIONS+=("${latest}:${minor}") + done + + echo "Discovered versions: ${VERSIONS[*]}" + + # Generate version dropdown TOML (single source of truth for + # both the latest and all archived builds). + VERSIONS_TOML=$'\n# Version entries for the version selector dropdown.\n' + VERSIONS_TOML+=$'[[params.versions]]\n version = "latest"\n url = "'"${BASE_PATH}"'/"'$'\n' + for entry in "${VERSIONS[@]}"; do + TAG="${entry%%:*}" + LABEL="${entry##*:}" + VERSIONS_TOML+=$'\n[[params.versions]]\n' + VERSIONS_TOML+=" version = \"${TAG}\""$'\n' + VERSIONS_TOML+=" url = \"${BASE_PATH}/${LABEL}/\""$'\n' + done + + # Persist for subsequent steps + echo "${VERSIONS_TOML}" >> docs/hugo.toml + printf '%s\n' "${VERSIONS[@]}" > /tmp/versions.txt + - name: Build latest docs env: - # For maximum backward compatibility with Hugo modules HUGO_ENVIRONMENT: production HUGO_ENV: production TZ: America/Los_Angeles @@ -76,6 +108,75 @@ jobs: --gc \ --minify \ --baseURL "${{ steps.pages.outputs.base_url }}/" + - name: Build versioned docs + env: + HUGO_ENVIRONMENT: production + HUGO_ENV: production + TZ: America/Los_Angeles + run: | + BASE_URL="${{ steps.pages.outputs.base_url }}" + BASE_PATH="$(echo "${BASE_URL}" | sed 's|https\?://[^/]*||')" + + # Read versions and TOML generated by the previous step + mapfile -t VERSIONS < /tmp/versions.txt + VERSIONS_TOML="$(sed -n '/^# Version entries/,$p' docs/hugo.toml)" + + for entry in "${VERSIONS[@]}"; do + TAG="${entry%%:*}" + LABEL="${entry##*:}" + echo "::group::Building docs for ${LABEL} (from tag ${TAG})" + + WORKDIR="/tmp/docs-${LABEL}" + mkdir -p "${WORKDIR}" + + # Extract docs directory from the tagged version + git archive "${TAG}" -- docs/ | tar -x -C "${WORKDIR}" + + # Copy node_modules for PostCSS (shared across all builds) + cp -r docs/node_modules "${WORKDIR}/docs/" 2>/dev/null || true + + # Use current go.mod/go.sum so all builds use Docsy v0.14.3. + # Older tags used Docsy v0.11.0 which is incompatible with the + # Hugo version installed in CI (render hook naming changed). + cp docs/go.mod docs/go.sum "${WORKDIR}/docs/" + + # Replace layouts and assets with the current version so that + # archived builds use compatible templates and consistent styling. + rm -rf "${WORKDIR}/docs/layouts" + cp -r docs/layouts "${WORKDIR}/docs/layouts" + rm -rf "${WORKDIR}/docs/assets" + cp -r docs/assets "${WORKDIR}/docs/assets" + + # Patch hugo.toml for archived version + HUGO_TOML="${WORKDIR}/docs/hugo.toml" + sed -i 's/^version = .*/version = "'"${TAG}"'"/' "${HUGO_TOML}" + sed -i 's/^archived_version = .*/archived_version = true/' "${HUGO_TOML}" + + # Remove any existing version dropdown entries so future tags + # that already contain [[params.versions]] do not get duplicates. + sed -i '/^\[\[params\.versions\]\]/,/^$/d' "${HUGO_TOML}" + + # Append version dropdown entries + echo "${VERSIONS_TOML}" >> "${HUGO_TOML}" + + # Build Hugo for this version. + # HUGO_ENABLEGITINFO=false because git archive extracts files + # without a .git directory, so git log would fail otherwise. + # Run from the source directory (not via --source) so that Go + # module resolution reads the correct go.mod. + (cd "${WORKDIR}/docs" && HUGO_ENABLEGITINFO=false hugo \ + --gc \ + --minify \ + --baseURL "${BASE_URL}/${LABEL}/") + + # Move output into the latest build's public directory as a subdirectory + mv "${WORKDIR}/docs/public" "docs/public/${LABEL}" + + # Clean up + rm -rf "${WORKDIR}" + + echo "::endgroup::" + done - name: Upload artifact uses: actions/upload-pages-artifact@v5 with: diff --git a/docs/content/en/docs/documentation/dependent-resource-and-workflows/dependent-resources.md b/docs/content/en/docs/documentation/dependent-resource-and-workflows/dependent-resources.md index 13310a3c42..2b3e317baa 100644 --- a/docs/content/en/docs/documentation/dependent-resource-and-workflows/dependent-resources.md +++ b/docs/content/en/docs/documentation/dependent-resource-and-workflows/dependent-resources.md @@ -188,7 +188,7 @@ usually limited to status handling based on the state of the secondary resources resources are not dependent on each other. As an alternative, you can also invoke reconciliation explicitly, event for managed workflows. -See [Workflows](https://javaoperatorsdk.io/docs/documentation/dependent-resource-and-workflows/workflows/) for more details on how the dependent +See [Workflows](workflows.md) for more details on how the dependent resources are reconciled. This behavior and automated handling is referred to as "managed" because the `DependentResource` @@ -231,7 +231,7 @@ It is also possible to wire dependent resources programmatically. In practice th developer is responsible for initializing and managing the dependent resources as well as calling their `reconcile` method. However, this makes it possible for developers to fully customize the reconciliation process. Standalone dependent resources should be used in cases when the managed use -case does not fit. You can, of course, also use [Workflows](https://javaoperatorsdk.io/docs/documentation/dependent-resource-and-workflows/workflows/) when managing +case does not fit. You can, of course, also use [Workflows](workflows.md) when managing resources programmatically. You can see a commented example of how to do diff --git a/docs/content/en/docs/documentation/dependent-resource-and-workflows/workflows.md b/docs/content/en/docs/documentation/dependent-resource-and-workflows/workflows.md index 7efcc257c6..f4a739fd85 100644 --- a/docs/content/en/docs/documentation/dependent-resource-and-workflows/workflows.md +++ b/docs/content/en/docs/documentation/dependent-resource-and-workflows/workflows.md @@ -12,12 +12,12 @@ depends on the state of other resources or cannot be processed until these other a given state or some condition holds true for them. Dealing with such scenarios are therefore rather common for operators and the purpose of the workflow feature of the Java Operator SDK (JOSDK) is to simplify supporting such cases in a declarative way. Workflows build on top of the -[dependent resources](https://javaoperatorsdk.io/docs/documentation/dependent-resource-and-workflows/dependent-resources/) feature. +[dependent resources](dependent-resources.md) feature. While dependent resources focus on how a given secondary resource should be reconciled, workflows focus on orchestrating how these dependent resources should be reconciled. Workflows describe how as a set of -[dependent resources](https://javaoperatorsdk.io/docs/documentation/dependent-resource-and-workflows/dependent-resources/) (DR) depend on one +[dependent resources](dependent-resources.md) (DR) depend on one another, along with the conditions that need to hold true at certain stages of the reconciliation process. @@ -135,7 +135,7 @@ public class SampleWorkflowReconciler implements Reconciler