Merge pull request #12178 from rook/mergify/bp/release-1.11/pr-12110

docs: add support for autogenerated docs for CRDs (backport #12110)

.github/workflows/docs-check.yml

@@ -45,5 +45,15 @@ jobs:
       - name: Install mkdocs and dependencies
         run: cd build/release/ && make deps.docs
 
+      - name: Check documentation for CRDs
+        run: |
+          make validate-and-gen-docs-crds
+          DIFF_ON_DOCS=$(git diff --ignore-matching-lines='on git commit')
+          if [ ! -z "$DIFF_ON_DOCS" ]; then
+          echo "Please run 'make generate-docs-crds' locally, commit the updated crds docs, and push the change"
+          fi
+          git diff --ignore-matching-lines='on git commit' --exit-code
+
       - name: Build documentation using mkdocs
         run: make docs-build
+

Documentation/CRDs/.pages

@@ -5,4 +5,6 @@ nav:
     - Shared-Filesystem
     - Object-Storage
     - ceph-client-crd.md
+    - ceph-nfs-crd.md
+    - specification.md
     - ...

Documentation/gen-crd-api-reference-docs/template/members.tpl

@@ -0,0 +1,48 @@
+{{ define "members" }}
+
+{{ range .Members }}
+{{ if not (hiddenMember .)}}
+<tr>
+    <td>
+        <code>{{ fieldName . }}</code><br/>
+        <em>
+            {{ if linkForType .Type }}
+                <a href="{{ linkForType .Type}}">
+                    {{ typeDisplayName .Type }}
+                </a>
+            {{ else }}
+                {{ typeDisplayName .Type }}
+            {{ end }}
+        </em>
+    </td>
+    <td>
+        {{ if fieldEmbedded . }}
+            <p>
+                (Members of <code>{{ fieldName . }}</code> are embedded into this type.)
+            </p>
+        {{ end}}
+
+        {{ if isOptionalMember .}}
+            <em>(Optional)</em>
+        {{ end }}
+
+        {{ safe (renderComments .CommentLines) }}
+
+    {{ if and (eq (.Type.Name.Name) "ObjectMeta") }}
+        Refer to the Kubernetes API documentation for the fields of the
+        <code>metadata</code> field.
+    {{ end }}
+
+    {{ if or (eq (fieldName .) "spec") }}
+        <br/>
+        <br/>
+        <table>
+            {{ template "members" .Type }}
+        </table>
+    {{ end }}
+    </td>
+</tr>
+{{ end }}
+{{ end }}
+
+{{ end }}

Documentation/gen-crd-api-reference-docs/template/pkg.tpl

@@ -0,0 +1,49 @@
+{{ define "packages" }}
+
+{{ with .packages}}
+<p>Packages:</p>
+<ul>
+    {{ range . }}
+    <li>
+        <a href="#{{- packageAnchorID . -}}">{{ packageDisplayName . }}</a>
+    </li>
+    {{ end }}
+</ul>
+{{ end}}
+
+{{ range .packages }}
+    <h2 id="{{- packageAnchorID . -}}">
+        {{- packageDisplayName . -}}
+    </h2>
+
+    {{ with (index .GoPackages 0 )}}
+        {{ with .DocComments }}
+        <div>
+            {{ safe (renderComments .) }}
+        </div>
+        {{ end }}
+    {{ end }}
+
+    Resource Types:
+    <ul>
+    {{- range (visibleTypes (sortedTypes .Types)) -}}
+        {{ if isExportedType . -}}
+        <li>
+            <a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
+        </li>
+        {{- end }}
+    {{- end -}}
+    </ul>
+
+    {{ range (visibleTypes (sortedTypes .Types))}}
+        {{ template "type" .  }}
+    {{ end }}
+    <hr/>
+{{ end }}
+
+<p><em>
+    Generated with <code>gen-crd-api-reference-docs</code>
+    {{ with .gitCommit }} on git commit <code>{{ . }}</code>{{end}}.
+</em></p>
+
+{{ end }}

Documentation/gen-crd-api-reference-docs/template/placeholder.go

@@ -0,0 +1,2 @@
+// Placeholder file to make Go vendor this directory properly.
+package template

Documentation/gen-crd-api-reference-docs/template/type.tpl

@@ -0,0 +1,81 @@
+{{ define "type" }}
+
+<h3 id="{{ anchorIDForType . }}">
+    {{- .Name.Name }}
+    {{ if eq .Kind "Alias" }}(<code>{{.Underlying}}</code> alias){{ end -}}
+</h3>
+{{ with (typeReferences .) }}
+    <p>
+        (<em>Appears on:</em>
+        {{- $prev := "" -}}
+        {{- range . -}}
+            {{- if $prev -}}, {{ end -}}
+            {{- $prev = . -}}
+            <a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
+        {{- end -}}
+        )
+    </p>
+{{ end }}
+
+<div>
+    {{ safe (renderComments .CommentLines) }}
+</div>
+
+{{ with (constantsOfType .) }}
+<table>
+    <thead>
+        <tr>
+            <th>Value</th>
+            <th>Description</th>
+        </tr>
+    </thead>
+    <tbody>
+      {{- range . -}}
+      <tr>
+        {{- /*
+            renderComments implicitly creates a <p> element, so we
+            add one to the display name as well to make the contents
+            of the two cells align evenly.
+        */ -}}
+        <td><p>{{ typeDisplayName . }}</p></td>
+        <td>{{ safe (renderComments .CommentLines) }}</td>
+      </tr>
+      {{- end -}}
+    </tbody>
+</table>
+{{ end }}
+
+{{ if .Members }}
+<table>
+    <thead>
+        <tr>
+            <th>Field</th>
+            <th>Description</th>
+        </tr>
+    </thead>
+    <tbody>
+        {{ if isExportedType . }}
+        <tr>
+            <td>
+                <code>apiVersion</code><br/>
+                string</td>
+            <td>
+                <code>
+                    {{apiGroup .}}
+                </code>
+            </td>
+        </tr>
+        <tr>
+            <td>
+                <code>kind</code><br/>
+                string
+            </td>
+            <td><code>{{.Name.Name}}</code></td>
+        </tr>
+        {{ end }}
+        {{ template "members" .}}
+    </tbody>
+</table>
+{{ end }}
+
+{{ end }}

Makefile

@@ -134,6 +134,7 @@ do.build.parallel: $(foreach p,$(PLATFORMS_TO_BUILD_FOR), do.build.platform.$(p)
 build: csv-clean build.common ## Only build for linux platform
 	@$(MAKE) go.build PLATFORM=linux_$(GOHOSTARCH)
 	@$(MAKE) -C images PLATFORM=linux_$(GOHOSTARCH)
+	@$(MAKE) generate-docs-crds
 
 build.all: build.common ## Build source code for all platforms.
 ifneq ($(GOHOSTARCH),amd64)
@@ -215,6 +216,12 @@ docs-preview: ## Preview the documentation through mkdocs
 docs-build:  ## Build the documentation to the `site/` directory
 	mkdocs build --strict
 
+generate-docs-crds: ## Build the documentation for CRD
+	@build/crds/generate-crd-docs.sh
+
+validate-and-gen-docs-crds: ## Force generation of CRD documentation
+	build/crds/generate-crd-docs.sh --force
+
 .PHONY: all build.common
 .PHONY: build build.all install test check vet fmt codegen mod.check clean distclean prune
 

build/crds/generate-crd-docs.sh

@@ -0,0 +1,23 @@
+#! /usr/bin/env bash
+
+SCRIPT_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd -P)
+GEN_CRD_API_REFERENCE_DOC_VERSION=v0.3.0
+SCRIPT_CHECK_DOCS_DIFF=$(git diff --name-only --diff-filter=M | grep -Ec '/types\.go$')
+
+install_generator() {
+    go install github.com/ahmetb/gen-crd-api-reference-docs@${GEN_CRD_API_REFERENCE_DOC_VERSION}
+}
+
+run_gen() {
+  if [[  "$SCRIPT_CHECK_DOCS_DIFF" -gt 0 || "$1" = "--force" ]]; then
+    echo "differences found in types.go, rebuilding specification.md"
+    install_generator
+    gen-crd-api-reference-docs \
+        -config="${SCRIPT_ROOT}/crd-docs-config.json" \
+        -template-dir="${SCRIPT_ROOT}/Documentation/gen-crd-api-reference-docs/template" \
+        -api-dir="github.com/rook/rook/pkg/apis/ceph.rook.io" \
+        -out-file="${SCRIPT_ROOT}/Documentation/CRDs/specification.md"
+ fi
+}
+
+run_gen "$@"

crd-docs-config.json

@@ -0,0 +1,28 @@
+{
+  "hideMemberFields": [
+    "TypeMeta"
+  ],
+  "hideTypePatterns": [
+    "ParseError$",
+    "List$"
+  ],
+  "externalPackages": [
+    {
+      "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$",
+      "docsURLTemplate": "https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"
+    },
+    {
+      "typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis)/",
+      "docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}"
+    },
+    {
+      "typeMatchPrefix": "^github\\.com/knative/pkg/apis/duck/",
+      "docsURLTemplate": "https://pkg.go.dev/github.com/knative/pkg/apis/duck/{{arrIndex .PackageSegments -1}}#{{.TypeIdentifier}}"
+    }
+  ],
+  "typeDisplayNamePrefixOverrides": {
+    "k8s.io/api/": "Kubernetes ",
+    "k8s.io/apimachinery/pkg/apis/": "Kubernetes "
+  },
+  "markdownDisabled": false
+}

pkg/apis/ceph.rook.io/v1/types.go

@@ -1519,10 +1519,11 @@ type ObjectEndpoints struct {
 	Secure []string `json:"secure"`
 }
 
-// CephObjectStoreUser represents a Ceph Object Store Gateway User
 // +genclient
 // +genclient:noStatus
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+
+// CephObjectStoreUser represents a Ceph Object Store Gateway User
 // +kubebuilder:resource:shortName=rcou;objectuser
 // +kubebuilder:printcolumn:name="Phase",type=string,JSONPath=`.status.phase`
 // +kubebuilder:subresource:status
@@ -1613,10 +1614,11 @@ type ObjectUserQuotaSpec struct {
 	MaxObjects *int64 `json:"maxObjects,omitempty"`
 }
 
-// CephObjectRealm represents a Ceph Object Store Gateway Realm
 // +genclient
 // +genclient:noStatus
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+
+// CephObjectRealm represents a Ceph Object Store Gateway Realm
 // +kubebuilder:subresource:status
 type CephObjectRealm struct {
 	metav1.TypeMeta   `json:",inline"`
@@ -1648,10 +1650,11 @@ type PullSpec struct {
 	Endpoint string `json:"endpoint,omitempty"`
 }
 
-// CephObjectZoneGroup represents a Ceph Object Store Gateway Zone Group
 // +genclient
 // +genclient:noStatus
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+
+// CephObjectZoneGroup represents a Ceph Object Store Gateway Zone Group
 // +kubebuilder:printcolumn:name="Phase",type=string,JSONPath=`.status.phase`
 // +kubebuilder:subresource:status
 type CephObjectZoneGroup struct {
@@ -1677,10 +1680,11 @@ type ObjectZoneGroupSpec struct {
 	Realm string `json:"realm"`
 }
 
-// CephObjectZone represents a Ceph Object Store Gateway Zone
 // +genclient
 // +genclient:noStatus
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+
+// CephObjectZone represents a Ceph Object Store Gateway Zone
 // +kubebuilder:printcolumn:name="Phase",type=string,JSONPath=`.status.phase`
 // +kubebuilder:subresource:status
 type CephObjectZone struct {
@@ -1729,10 +1733,11 @@ type ObjectZoneSpec struct {
 	PreservePoolsOnDelete bool `json:"preservePoolsOnDelete"`
 }
 
-// CephBucketTopic represents a Ceph Object Topic for Bucket Notifications
 // +genclient
 // +genclient:noStatus
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+
+// CephBucketTopic represents a Ceph Object Topic for Bucket Notifications
 // +kubebuilder:printcolumn:name="Phase",type=string,JSONPath=`.status.phase`
 // +kubebuilder:subresource:status
 type CephBucketTopic struct {
@@ -1846,10 +1851,11 @@ type KafkaEndpointSpec struct {
 	AckLevel string `json:"ackLevel,omitempty"`
 }
 
-// CephBucketNotification represents a Bucket Notifications
 // +genclient
 // +genclient:noStatus
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+
+// CephBucketNotification represents a Bucket Notifications
 // +kubebuilder:subresource:status
 type CephBucketNotification struct {
 	metav1.TypeMeta   `json:",inline"`
@@ -1924,10 +1930,11 @@ type RGWServiceSpec struct {
 	Annotations Annotations `json:"annotations,omitempty"`
 }
 
-// CephNFS represents a Ceph NFS
 // +genclient
 // +genclient:noStatus
 // +kubebuilder:resource:shortName=nfs,path=cephnfses
+
+// CephNFS represents a Ceph NFS
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 // +kubebuilder:subresource:status
 type CephNFS struct {