Migrate documentation to Antora

.gitignore

@@ -53,6 +53,9 @@ generated-check
 # Integration test outputs
 tests/**/output
 
+# Locally-built Antora documentation site
+docs/build
+
 # Python for the release wizard
 venv
 __pycache__

Makefile

@@ -227,8 +227,16 @@ smoke-test: build-release-artifacts ## Run a full smoke test on a set of local r
 .PHONY: check
 check: lint test ## Do all checks, lints and tests for the Solr Operator
 
+# Antora's content aggregation is git-based, so the docs build only works in a
+# git checkout. Include it in `lint` only when .git is present; this skips it
+# for an unpacked release source tarball (e.g. `make check` during smoke tests).
+DOCS_LINT :=
+ifneq ($(wildcard $(PROJECT_DIR)/.git),)
+DOCS_LINT := check-docs
+endif
+
 .PHONY: lint
-lint: check-zk-op-version check-mod vet check-format check-licenses check-manifests check-generated check-helm ## Lint the codebase to check for formatting and correctness
+lint: check-zk-op-version check-mod vet check-format check-licenses check-manifests check-generated check-helm $(DOCS_LINT) ## Lint the codebase to check for formatting and correctness
 
 .PHONY: check-format
 check-format: ## Check the codebase to make sure it adheres to golang standards
@@ -329,6 +337,31 @@ helm-deploy-operator: helm-dependency-build docker-build ## Deploy the current v
 	helm install solr-operator helm/solr-operator --set image.version=$(TAG) --set image.repository=$(IMG) --set image.pullPolicy=Never
 
 
+##@ Documentation
+
+# Antora image used to build the docs site locally. Pinned to the Antora
+# version used by the Apache Solr Reference Guide build (apache/solr). This is
+# 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
+
+.PHONY: generate-antora-yaml
+generate-antora-yaml: ## Generate docs/antora.yml from version/version.go
+	./hack/docs/generate_antora_yaml.sh
+
+.PHONY: docs
+docs: generate-antora-yaml ## 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."
+
+.PHONY: docs-clean
+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)
+	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
 LOCALBIN ?= $(PROJECT_DIR)/bin
 $(LOCALBIN):

README.md

@@ -53,27 +53,27 @@ Join us on the [#solr-operator](https://kubernetes.slack.com/messages/solr-opera
 
 Please visit the following pages for documentation on using and developing the Solr Operator:
 
-- [Local Tutorial](https://apache.github.io/solr-operator/docs/local_tutorial)
+- [Local Tutorial](https://solr.apache.org/guide/operator/latest/getting-started/local-tutorial.html)
 - [Helm Instructions via Artifact Hub](https://artifacthub.io/packages/helm/apache-solr/solr-operator)
   - The released helm charts and their instructions should be used for all safe and stable deployments.
     The charts found in `helm/` are not guaranteed to be compatible with the last stable release, and should only be used for development purposes.
-- [Running the Solr Operator](https://apache.github.io/solr-operator/docs/running-the-operator)
-- [Known Issues](https://apache.github.io/solr-operator/docs/known-issues)
+- [Running the Solr Operator](https://solr.apache.org/guide/operator/latest/getting-started/running-the-operator.html)
+- [Known Issues](https://solr.apache.org/guide/operator/latest/upgrade-notes/known-issues.html)
 - Available Solr Resources
-    - [Solr Clouds](https://apache.github.io/solr-operator/docs/solr-cloud)
-    - [Solr Backups](https://apache.github.io/solr-operator/docs/solr-backup)
-    - [Solr Metrics](https://apache.github.io/solr-operator/docs/solr-prometheus-exporter)
-- [Development](https://apache.github.io/solr-operator/docs/development)
+    - [Solr Clouds](https://solr.apache.org/guide/operator/latest/solr-cloud/index.html)
+    - [Solr Backups](https://solr.apache.org/guide/operator/latest/solr-backup/index.html)
+    - [Solr Metrics](https://solr.apache.org/guide/operator/latest/solr-prometheus-exporter/index.html)
+- [Development](https://solr.apache.org/guide/operator/latest/development/development.html)
 
 ### Examples
 
 Example uses of each CRD have been [provided](https://apache.github.io/solr-operator/example).
 
 ## Version Compatibility & Upgrade Notes
 
-Make sure to check the [Solr Operator Upgrade notes](docs/upgrade-notes.md), before upgrading the Solr Operator or CRDs in your Kubernetes cluster.
+Make sure to check the [Solr Operator Upgrade notes](https://solr.apache.org/guide/operator/latest/upgrade-notes/upgrade-notes.html), before upgrading the Solr Operator or CRDs in your Kubernetes cluster.
 
-This page also contains [Version Compatibility Matrixes](docs/upgrade-notes.md#version-compatibility-matrixes), which detail the compatible Solr versions and Kubernetes versions for each release of the Solr Operator.
+This page also contains [Version Compatibility Matrixes](https://solr.apache.org/guide/operator/latest/upgrade-notes/upgrade-notes.html#version-compatibility-matrixes), which detail the compatible Solr versions and Kubernetes versions for each release of the Solr Operator.
 
 ## Contributions
 

docs/antora.template.yml

@@ -0,0 +1,42 @@
+# 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.
+
+# DO NOT EDIT docs/antora.yml directly -- it is GENERATED from this template
+# (docs/antora.template.yml) by `make generate-antora-yaml`
+# (hack/docs/generate_antora_yaml.sh), which fills the @...@ tokens below from
+# version/version.go. Make documentation/version changes in this template.
+name: operator
+title: Apache Solr Operator
+version: '@ANTORA_VERSION@'
+display_version: '@DISPLAY_VERSION@'
+@PRERELEASE_LINE@
+start_page: ROOT:index.adoc
+nav:
+  - modules/ROOT/nav.adoc
+  - modules/getting-started/nav.adoc
+  - modules/solr-cloud/nav.adoc
+  - modules/solr-backup/nav.adoc
+  - modules/solr-prometheus-exporter/nav.adoc
+  - modules/upgrade-notes/nav.adoc
+  - modules/development/nav.adoc
+asciidoc:
+  attributes:
+    idseparator: '-'
+    idprefix: ''
+    # Full operator version (no leading 'v'), e.g. used in install snippets.
+    operator-version: '@OPERATOR_VERSION@'
+    # Link target for the Solr Reference Guide (absolute so it resolves in
+    # both the local operator-only preview and the combined official site).
+    solr-ref-guide: 'https://solr.apache.org/guide/solr/latest/'

docs/antora.yml

@@ -0,0 +1,42 @@
+# 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.
+
+# DO NOT EDIT docs/antora.yml directly -- it is GENERATED from this template
+# (docs/antora.template.yml) by `make generate-antora-yaml`
+# (hack/docs/generate_antora_yaml.sh), which fills the @...@ tokens below from
+# version/version.go. Make documentation/version changes in this template.
+name: operator
+title: Apache Solr Operator
+version: '0_10'
+display_version: 'v0.10-prerelease'
+prerelease: -prerelease
+start_page: ROOT:index.adoc
+nav:
+  - modules/ROOT/nav.adoc
+  - modules/getting-started/nav.adoc
+  - modules/solr-cloud/nav.adoc
+  - modules/solr-backup/nav.adoc
+  - modules/solr-prometheus-exporter/nav.adoc
+  - modules/upgrade-notes/nav.adoc
+  - modules/development/nav.adoc
+asciidoc:
+  attributes:
+    idseparator: '-'
+    idprefix: ''
+    # Full operator version (no leading 'v'), e.g. used in install snippets.
+    operator-version: '0.10.0'
+    # Link target for the Solr Reference Guide (absolute so it resolves in
+    # both the local operator-only preview and the combined official site).
+    solr-ref-guide: 'https://solr.apache.org/guide/solr/latest/'