feat: Link the CRD reference on the Stackable Hub (#888)

* feat: Link the CRD reference on the Stackable Hub

The docs' own pages now link https://hub.stackable.tech/crds instead of
the old CRD browser on crds.stackable.tech, using the new attributes:

  crd-ref: the listing
  {crd-ref}/<group>/<apiVersion>/<kind>{crd-ref-release}: a deep link

crd-ref-release is ?release=dev on this branch and gets the release
number on release branches (like crd-docs-version today).

The old crd-docs attributes stay until the operator repos migrate their
deep links to crd-ref (they do so in the planned operator sweep, one PR
per repo). page-crd-docs is removed: nothing in the UI templates reads
it.

The OIDC provider deep link loses its per-property anchor: the Hub has
section-level anchors only, so it points at #provider now.

* fix: Rewrite crd-ref-release when cutting a release branch

make-release-branch.sh already rewrites version, prerelease and
crd-docs-version; without this, a release branch would keep
?release=dev and its Hub CRD links would show bleeding-edge schemas.
The Hub names releases by major.minor, so this uses DOCS_VERSION
(e.g. 26.7), not VERSION (e.g. 26.7.1); the Hub 301s patch-level
values but major.minor is canonical.

* docs: Remind release cutters about crd-ref-release

Same kind of reminder comment that crd-docs-version has, in case the
attribute is ever edited by hand instead of via the release script.

Author: lfrancke

antora.yml

@@ -27,13 +27,19 @@ asciidoc:
     # Whether this version is already end of life.
     # If true, a banner will be displayed informing the user.
     end-of-life: false
-    # use the attributes below to link to the CRD docs
+    # The CRD reference on the Stackable Hub. crd-ref links the listing;
+    # deep links follow {crd-ref}/<group>/<apiVersion>/<kind>{crd-ref-release}
+    crd-ref: "https://hub.stackable.tech/crds"
+    # Keep this in line with the 'version' key above: '?release=dev' on main,
+    # '?release=<major.minor>' on release branches (the release script sets it).
+    crd-ref-release: "?release=dev"
+    # DEPRECATED: the old CRD browser attributes below are still used by the
+    # operator docs; they migrate to crd-ref repo by repo (operator sweep).
     crd-docs-base-url: "https://crds.stackable.tech"
     # used by the operator index pages, see the
     # operator-link-bar.adoc partial in the ROOT module
     hub-base-url: "https://hub.stackable.tech"
     crd-docs: "{crd-docs-base-url}/{crd-docs-version}"
     # to make attributes accessible to the UI template, they need to
     # be prefixed with "page-"
-    page-crd-docs: "{crd-docs}"
     page-end-of-life: "{end-of-life}"

modules/ROOT/pages/index.adoc

@@ -118,7 +118,7 @@ xref:operators:index.adoc[Operator overview]
 
 Read the CustomResourceDefinition (CRD) reference for all CRDs that are deployed by any Stackable operator.
 
-{crd-docs}[CRD Reference {external-link-icon}^]
+{crd-ref}{crd-ref-release}[CRD Reference {external-link-icon}^]
 
 ++++
 </div>

modules/concepts/pages/authentication.adoc

@@ -38,7 +38,7 @@ In a diagram it would look like this:
 
 image::image$authentication-overview.drawio.svg[]
 
-NOTE: Learn more in the xref:tutorials:authentication_with_openldap.adoc[OpenLDAP tutorial] and get a full overview of all the properties in the {crd-docs}/authentication.stackable.tech/authenticationclass/v1alpha1/#spec-provider-ldap[AuthenticationClass LDAP provider CRD reference{external-link-icon}^].
+NOTE: Learn more in the xref:tutorials:authentication_with_openldap.adoc[OpenLDAP tutorial] and get a full overview of all the properties in the {crd-ref}/authentication.stackable.tech/v1alpha1/authenticationclass{crd-ref-release}#provider.ldap[AuthenticationClass LDAP provider CRD reference{external-link-icon}^].
 
 [#OIDC]
 === OpenID Connect
@@ -59,7 +59,7 @@ include::example$authenticationclass-keycloak.yaml[]
 <7> Optionally enable TLS and configure verification. When present, connections to the idP will use `https://` instead of `http://`. See xref:tls-server-verification.adoc[].
 <8> Trust certificates signed by commonly trusted Certificate Authorities.
 
-NOTE: Get a full overview of all the properties in the {crd-docs}/authentication.stackable.tech/authenticationclass/v1alpha1/#spec-provider-oidc[AuthenticationClass OIDC provider CRD reference{external-link-icon}^].
+NOTE: Get a full overview of all the properties in the {crd-ref}/authentication.stackable.tech/v1alpha1/authenticationclass{crd-ref-release}#provider.oidc[AuthenticationClass OIDC provider CRD reference{external-link-icon}^].
 
 [#tls]
 === TLS
@@ -113,4 +113,4 @@ include::example$authenticationclass-static-secret.yaml[]
 == Further reading
 
 * xref:tutorials:authentication_with_openldap.adoc[] tutorial
-* {crd-docs}/authentication.stackable.tech/authenticationclass/v1alpha1/[AuthenticationClass CRD reference{external-link-icon}^]
+* {crd-ref}/authentication.stackable.tech/v1alpha1/authenticationclass{crd-ref-release}[AuthenticationClass CRD reference{external-link-icon}^]

modules/concepts/pages/s3.adoc

@@ -284,4 +284,4 @@ region:
 
 == What's next
 
-Read the {crd-docs}/s3.stackable.tech/s3bucket/v1alpha1/[S3Bucket CRD reference{external-link-icon}^] and the {crd-docs}/s3.stackable.tech/s3connection/v1alpha1/[S3Connection CRD reference{external-link-icon}^].
+Read the {crd-ref}/s3.stackable.tech/v1alpha1/s3bucket{crd-ref-release}[S3Bucket CRD reference{external-link-icon}^] and the {crd-ref}/s3.stackable.tech/v1alpha1/s3connection{crd-ref-release}[S3Connection CRD reference{external-link-icon}^].

modules/reference/nav.adoc

@@ -1,4 +1,4 @@
 * Reference
-** {crd-docs}[CRD Reference {external-link-icon}^]
+** {crd-ref}{crd-ref-release}[CRD Reference {external-link-icon}^]
 ** xref:glossary.adoc[]
 ** xref:duration.adoc[]

modules/tutorials/pages/authentication_with_openldap.adoc

@@ -367,7 +367,7 @@ The LDAP connection details only need to be written down once, in the Authentica
 == Further Reading
 
 - xref:concepts:authentication.adoc[Authentication concepts page]
-* {crd-docs}/authentication.stackable.tech/authenticationclass/v1alpha1/[AuthenticationClass CRD reference{external-link-icon}^]
+* {crd-ref}/authentication.stackable.tech/v1alpha1/authenticationclass{crd-ref-release}[AuthenticationClass CRD reference{external-link-icon}^]
 - xref:superset:getting_started/index.adoc[Getting started with the Stackable Operator for Apache Superset]
 - xref:trino:getting_started/index.adoc[Getting started with the Stackable Operator for Trino]
 // TODO Operator docs for LDAP

scripts/make-release-branch.sh

@@ -120,6 +120,10 @@ sed -i "s/^prerelease:.*/prerelease: false/" "$ANTORA_YAML_FILE"
 # Set crd-docs-version key to the 'version' variable
 sed -i "s/^\(\s*\)crd-docs-version:.*/\1crd-docs-version: \"$VERSION\"/" "$ANTORA_YAML_FILE"
 
+# Set the Hub release for the CRD reference links. The Hub names releases
+# by major.minor, so this uses DOCS_VERSION, not VERSION.
+sed -i "s/^\(\s*\)crd-ref-release:.*/\1crd-ref-release: \"?release=$DOCS_VERSION\"/" "$ANTORA_YAML_FILE"
+
 # Display changes using git diff
 git diff "$ANTORA_YAML_FILE"