Migrate documentation to Antora#834
Merged
Merged
Conversation
First step toward publishing the operator docs as a component of the Apache Solr Reference Guide: make the docs buildable as an Antora component that contributors can preview locally. - docs/antora.template.yml + generated docs/antora.yml define the 'operator' component. hack/docs/generate_antora_yaml.sh derives the Antora component version from version/version.go so it stays in sync with the operator version without requiring Gradle. - docs/modules/ROOT provides an initial landing page and navigation. - docs/local-playbook.yml plus the new `make docs` target render a local preview using the stock antora/antora image and the Solr Reference Guide UI bundle. - `make check-docs` validates the build (no broken references) and is wired into `make lint`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Convert the 16 user-facing Markdown docs into the 'operator' Antora component, grouped into modules (getting-started, solr-cloud, solr-backup, solr-prometheus-exporter, upgrade-notes, development), so they can be published alongside the Solr Reference Guide. - All pages converted to AsciiDoc with per-module nav files and the component nav list in antora.template.yml; landing page links to each section via xref. - Inbound links updated from apache.github.io/solr-operator/docs/* to solr.apache.org/guide/operator/latest/* in the top-level README, both helm chart READMEs, and helm/solr/values.yaml. - Release tooling repointed at the new docs: propagate_version.sh now updates the .adoc install snippets and regenerates docs/antora.yml, and the zookeeper-operator version check reads development.adoc. Verified locally with `make check-docs` (no broken references or AsciiDoc warnings). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The SolrCloud CRD and SolrBackup pages were large single documents. Now that the docs are a versioned Antora site, split them into focused pages and remove the per-feature "Since vX.Y.Z" annotations (version context is provided by the versioned site itself). - SolrCloud CRD overview keeps the common options and links out to its own pages: addressability, zookeeper, custom-solr-config, tls, and authentication-and-authorization (addressability is split out on its own to leave room for future expansion). - SolrBackup splits the repository-type reference into backup-repositories. - All cross-references updated: in-page <<>> links that crossed a new page boundary became xrefs, inbound xrefs from other pages were repointed to the new pages, and helm chart README/values.yaml links were updated to the new page URLs. - Removed 31 "_Since vX.Y.Z_" markers across 12 pages. Verified locally with `make check-docs`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Retitle the SolrBackup pages ("Managing Backups", "Repository Types")
and list backup-repositories as a top-level nav entry rather than nested
under the overview.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
anshumg
approved these changes
Jun 9, 2026
anshumg
left a comment
anshumg
left a comment
Contributor
There was a problem hiding this comment.
Sanity checked and it looks good to me. Certainly didn't read it all :)
Thanks @HoustonPutman !
anshumg
reviewed
Jun 9, 2026
| --> | ||
|
|
||
| # Solr on Kubernetes on local Mac | ||
| = Solr on Kubernetes on local Mac |
Contributor
There was a problem hiding this comment.
Should the license header be before the first line?
Contributor
Author
There was a problem hiding this comment.
Apparently not, the solr ref guide is the same way
HoustonPutman
added a commit
that referenced
this pull request
Jun 9, 2026
…aged (#835) 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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of #833
make docswill build a local version of the site (without Solr).make check-docswill validate everything. This is now included in the linting process.