Generate antora.yml for local builds; keep committed file release-managed

Follow up from #834

The committed docs/antora.yml is what the published Reference Guide uses for
a branch, so it must reflect that branch's released version (not a prerelease)
and should only change at release time. Previously `make docs` and
propagate_version.sh regenerated it from version/version.go on every run,
leaving release branches showing a prerelease version.

Mirror Solr's approach:
- `make docs`/`check-docs` now stage a build dir (docs/build/staging) with a
  throwaway antora.yml generated from version/version.go, so local previews
  show the in-development version without touching the committed file.
- generate_antora_yaml.sh takes -o (output) for staging.
- Remove antora.yml regeneration from propagate_version.sh; the release wizard
  regenerates the committed docs/antora.yml at release (after the prerelease
  suffix is stripped), so it reflects the released version.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: HoustonPutman

Makefile

@@ -344,13 +344,27 @@ helm-deploy-operator: helm-dependency-build docker-build ## Deploy the current v
 # for local previewing only; the official site is published as an additional
 # component of the Reference Guide from the apache/solr repo.
 ANTORA_IMAGE ?= antora/antora:3.1.12
+DOCS_STAGING = docs/build/staging
 
 .PHONY: generate-antora-yaml
-generate-antora-yaml: ## Generate docs/antora.yml from version/version.go
+# Writes the COMMITTED docs/antora.yml. This descriptor drives the published
+# site for this branch, so it is only run at release time (by the release
+# wizard) to reflect the released version -- NOT on every local build.
+generate-antora-yaml: ## Regenerate the committed docs/antora.yml (release use)
 	./hack/docs/generate_antora_yaml.sh
 
+.PHONY: docs-staging
+# Stages a build dir with the modules and a throwaway antora.yml generated from
+# version/version.go, so local previews show the in-development version without
+# modifying the committed docs/antora.yml.
+docs-staging:
+	rm -rf $(DOCS_STAGING)
+	mkdir -p $(DOCS_STAGING)
+	cp -r docs/modules $(DOCS_STAGING)/modules
+	./hack/docs/generate_antora_yaml.sh -o $(DOCS_STAGING)/antora.yml
+
 .PHONY: docs
-docs: generate-antora-yaml ## Build the operator Antora docs site locally for previewing (requires Docker)
+docs: docs-staging ## Build the operator Antora docs site locally for previewing (requires Docker)
 	docker run --rm -v "$(PROJECT_DIR):/antora" -w /antora/docs $(ANTORA_IMAGE) --fetch --to-dir build/site local-playbook.yml
 	@echo "Docs built. Open docs/build/site/index.html in a browser to preview."
 
@@ -359,7 +373,7 @@ docs-clean: ## Remove the locally-generated documentation site
 	rm -rf docs/build
 
 .PHONY: check-docs
-check-docs: generate-antora-yaml ## Validate the operator docs build with no broken references (requires Docker)
+check-docs: docs-staging ## Validate the operator docs build with no broken references (requires Docker)
 	docker run --rm -v "$(PROJECT_DIR):/antora" -w /antora/docs $(ANTORA_IMAGE) --fetch --log-failure-level=warn --to-dir build/site local-playbook.yml
 
 ##@ Dependencies

docs/local-playbook.yml

@@ -37,7 +37,7 @@ content:
     - url: ..
       # HEAD builds the current worktree, including uncommitted changes.
       branches: HEAD
-      start_path: docs
+      start_path: docs/build/staging
       # No "edit this page" links in local preview.
       edit_url: false
 

hack/docs/generate_antora_yaml.sh

@@ -14,29 +14,43 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Generates docs/antora.yml from docs/antora.template.yml, deriving the Antora
-# component version from version/version.go. This keeps the Antora version in
-# lock-step with the operator version without requiring Gradle (unlike Solr).
+# Generates an Antora component descriptor (antora.yml) for the operator docs
+# from docs/antora.template.yml, deriving the version from version/version.go.
 #
-#   v0.10.0 (suffix "")           -> version '0_10', display_version '0.10'
-#   v0.10.0 (suffix "prerelease") -> version '0_10', display_version '0.10-prerelease', prerelease: -prerelease
+# By default it writes the COMMITTED docs/antora.yml -- the descriptor the
+# published Reference Guide uses for this branch. The release wizard regenerates
+# it (via `make generate-antora-yaml`) at the steps where the published version
+# changes; it is deliberately NOT regenerated on the post-release patch bump, so
+# a release branch stays pinned to its last released version. Local preview
+# builds (`make docs`) pass -o to write a throwaway descriptor into the
+# build/staging directory, so the committed file is never modified during a
+# normal build.
+#
+# Usage: generate_antora_yaml.sh [-o OUTPUT]
+#   -o OUTPUT   output file (default: docs/antora.yml)
+#
+#   version.go v0.9.1                -> version '0_9',  display_version 'v0.9'
+#   version.go v0.10.0 (prerelease)  -> version '0_10', display_version 'v0.10-prerelease', prerelease: -prerelease
 
 set -eu
 set -o pipefail
 
-# Resolve the project root (this script lives in hack/docs/).
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd)"
-
-VERSION_GO="${PROJECT_DIR}/version/version.go"
 TEMPLATE="${PROJECT_DIR}/docs/antora.template.yml"
 OUTPUT="${PROJECT_DIR}/docs/antora.yml"
 
-# Parse Version (e.g. v0.10.0) and VersionSuffix (e.g. prerelease) from version.go.
+while getopts ":o:" opt; do
+  case "${opt}" in
+    o) OUTPUT="${OPTARG}" ;;
+    *) echo "Usage: $0 [-o OUTPUT]" >&2; exit 2 ;;
+  esac
+done
+
+VERSION_GO="${PROJECT_DIR}/version/version.go"
 RAW_VERSION="$(grep -E 'Version([[:space:]]+)=' "${VERSION_GO}" | head -1 | sed -E 's/.*["'"'"']([^"'"'"']*)["'"'"'].*/\1/')"
 SUFFIX="$(grep -E 'VersionSuffix([[:space:]]+)=' "${VERSION_GO}" | sed -E 's/.*["'"'"']([^"'"'"']*)["'"'"'].*/\1/')"
 
-# Strip leading 'v' and split into semver parts.
 SEMVER="${RAW_VERSION#v}"
 IFS='.' read -r MAJOR MINOR PATCH <<< "${SEMVER}"
 
@@ -51,6 +65,7 @@ else
   PRERELEASE_LINE=""
 fi
 
+mkdir -p "$(dirname "${OUTPUT}")"
 # Substitute tokens. Use '|' as the sed delimiter; values contain no '|'.
 sed \
   -e "s|@ANTORA_VERSION@|${ANTORA_VERSION}|g" \

hack/release/version/propagate_version.sh

@@ -98,9 +98,4 @@ fi
 } > helm/solr/README.md.tmp && mv helm/solr/README.md.tmp helm/solr/README.md
 
 
-# Regenerate the operator Antora component descriptor (docs/antora.yml) from
-# version/version.go. Docs pages reference the version via the {operator-version}
-# attribute defined there, so no per-page version edits are needed.
-./hack/docs/generate_antora_yaml.sh
-
 make manifests

hack/release/wizard/releaseWizard.yaml

@@ -458,6 +458,10 @@ groups:
       - !Command
         cmd: make propagate-version
         tee: true
+      - !Command
+        cmd: make generate-antora-yaml
+        comment: Regenerate the committed docs/antora.yml for the new version.
+        tee: true
       - !Command
         comment: Make sure the edits done by propagating the version are ok, then push
         cmd: git add -u .  && git commit -m "Add next major version {{ next_version }}"  && git push
@@ -490,6 +494,10 @@ groups:
       - !Command
         cmd: make propagate-version
         tee: true
+      - !Command
+        cmd: make generate-antora-yaml
+        comment: Regenerate the committed docs/antora.yml for the new version.
+        tee: true
       - !Command
         comment: Make sure the edits done by propagating the version are ok, then push
         cmd: git add -u .  && git commit -m "Add next minor version {{ next_version }}"  && git push
@@ -755,10 +763,14 @@ groups:
         comment: Remove the prerelase suffix from the version.
         stdout: true
       - !Command
-        cmd: ./hack/release/version/propagate_version.sh
+        cmd: make propagate-version
         comment: Propagate the new version throughout the repo.
         logfile: propagate_version.log
         tee: true
+      - !Command
+        cmd: make generate-antora-yaml
+        comment: Regenerate the committed docs/antora.yml to the released version.
+        tee: true
       - !Command
         cmd: ./hack/release/artifacts/set_signing_key.sh -f "{{ gpg_fingerprint | default('<gpg_fingerprint>', True) }}"
         comment: Set the signing key throughout the repo.