feat: add CRD docs auto generator tooling (keptn#884)

Signed-off-by: Amishakumari544 <[email protected]>

.github/scripts/generate-crd-docs/crd-docs-generator-config.yaml

@@ -0,0 +1,9 @@
+processor:
+  useRawDocstring: true
+  ignoreTypes: [ ]
+  ignoreFields:
+    - "status$"
+    - "TypeMeta$"
+
+render:
+  kubernetesVersion: 1.24

.github/scripts/generate-crd-docs/generate-crd-docs.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+
+# CRD docs auto generation script
+#
+# This script goes through all API definitions in the operator/apis folder
+# and generates docs from code for each API group and version
+#
+# Inputs: None
+
+# renovate: datasource=github-releases depName=elastic/crd-ref-docs
+GENERATOR_VERSION=master
+API_DOMAIN="keptn.sh"
+API_ROOT='operator/apis/'
+TEMPLATE_DIR='.github/scripts/generate-crd-docs/templates'
+RENDERER='markdown'
+RENDERER_CONFIG_FILE='.github/scripts/generate-crd-docs/crd-docs-generator-config.yaml'
+
+echo "Checking if code generator tool is installed..."
+test -s crd-ref-docs || go install github.com/elastic/crd-ref-docs@${GENERATOR_VERSION}
+
+echo "Running CRD docs auto-generator..."
+
+for api_group in "$API_ROOT"*; do
+  sanitized_api_group="${api_group#$API_ROOT}"
+  INDEX_PATH="./docs/content/en/docs/crd-ref/$sanitized_api_group/_index.md"
+
+  if [ ! -f "$INDEX_PATH" ]; then
+    echo "API group index file doesn't exist for group $sanitized_api_group. Creating it now..."
+    # Use sanitized_api_group and make first char uppercase
+    API_GROUP="$(tr '[:lower:]' '[:upper:]' <<< "${sanitized_api_group:0:1}")${sanitized_api_group:1}"
+    export API_GROUP
+    envsubst < './.github/scripts/generate-crd-docs/templates/index-template.md' > "$INDEX_PATH"
+    unset API_GROUP
+  fi
+
+  for api_version in "$api_group"/*; do
+    sanitized_api_version="${api_version#$API_ROOT$sanitized_api_group/}"
+
+    OUTPUT_PATH="./docs/content/en/docs/crd-ref/$sanitized_api_group/$sanitized_api_version"
+
+    echo "Arguments:"
+    echo "TEMPLATE_DIR: $TEMPLATE_DIR"
+    echo "API_ROOT: $API_ROOT"
+    echo "API_GROUP: $sanitized_api_group"
+    echo "API_VERSION: $sanitized_api_version"
+    echo "RENDERER: $RENDERER"
+    echo "RENDERER_CONFIG_FILE: $RENDERER_CONFIG_FILE"
+    echo "OUTPUT_PATH: $OUTPUT_PATH/_index.md"
+
+    echo "Creating docs folder $OUTPUT_PATH..."
+    mkdir -p "$OUTPUT_PATH"
+
+    echo "Generating CRD docs for $sanitized_api_group.$API_DOMAIN/$sanitized_api_version..."
+    crd-ref-docs \
+      --templates-dir "$TEMPLATE_DIR" \
+      --source-path="./$api_version" \
+      --renderer="$RENDERER" \
+      --config "$RENDERER_CONFIG_FILE" \
+      --output-path "$OUTPUT_PATH/_index.md"
+    echo "---------------------"
+  done
+done

.github/scripts/generate-crd-docs/templates/gv_details.tpl

@@ -0,0 +1,19 @@
+{{- define "gvDetails" -}}
+{{- $gv := . -}}
+
+## {{ $gv.GroupVersionString }}
+
+{{ $gv.Doc }}
+
+{{- if $gv.Kinds  }}
+### Resource Types
+{{- range $gv.SortedKinds }}
+- {{ $gv.TypeForKind . | markdownRenderTypeLink }}
+{{- end }}
+{{ end }}
+
+{{ range $gv.SortedTypes }}
+{{ template "type" . }}
+{{ end }}
+
+{{- end -}}

.github/scripts/generate-crd-docs/templates/gv_list.tpl

@@ -0,0 +1,21 @@
+{{- define "gvList" -}}
+{{- $groupVersions := . -}}
+{{- $groupVersion := index $groupVersions 0 -}}
+
+---
+title: {{ $groupVersion.Version }}
+description: Reference information for {{ $groupVersion.GroupVersionString }}
+---
+<!-- markdownlint-disable -->
+
+## Packages
+{{- range $groupVersions }}
+- {{ markdownRenderGVLink . }}
+{{- end }}
+
+{{ range $groupVersions }}
+{{ template "gvDetails" . }}
+{{ end }}
+
+{{- end -}}
+<!-- markdownlint-enable -->

.github/scripts/generate-crd-docs/templates/index-template.md

@@ -0,0 +1,4 @@
+---
+title: $API_GROUP API
+description: Reference information about the $API_GROUP API
+---

.github/scripts/generate-crd-docs/templates/type.tpl

@@ -0,0 +1,33 @@
+{{- define "type" -}}
+{{- $type := . -}}
+{{- if markdownShouldRenderType $type -}}
+
+#### {{ $type.Name }}
+
+{{ if $type.IsAlias }}_Underlying type:_ `{{ markdownRenderTypeLink $type.UnderlyingType  }}`{{ end }}
+
+{{ $type.Doc }}
+
+{{ if $type.References -}}
+_Appears in:_
+{{- range $type.SortedReferences }}
+- {{ markdownRenderTypeLink . }}
+{{- end }}
+{{- end }}
+
+{{ if $type.Members -}}
+| Field | Description |
+| --- | --- |
+{{ if $type.GVK -}}
+| `apiVersion` _string_ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}`
+| `kind` _string_ | `{{ $type.GVK.Kind }}`
+{{ end -}}
+
+{{ range $type.Members -}}
+| `{{ .Name  }}` _{{ markdownRenderType .Type }}_ | {{ template "type_members" . }} |
+{{ end -}}
+
+{{ end -}}
+
+{{- end -}}
+{{- end -}}

.github/scripts/generate-crd-docs/templates/type_members.tpl

@@ -0,0 +1,8 @@
+{{- define "type_members" -}}
+{{- $field := . -}}
+{{- if eq $field.Name "metadata" -}}
+Refer to Kubernetes API documentation for fields of `metadata`.
+{{- else -}}
+{{ $field.Doc }}
+{{- end -}}
+{{- end -}}

.github/workflows/markdown-checks.yaml

@@ -14,6 +14,9 @@ on:
     paths:
       - '**.md'
 
+env:
+  GO_VERSION: "~1.19"
+
 defaults:
   run:
     shell: bash
@@ -55,3 +58,35 @@ jobs:
 
       - name: Lint Markdown files
         run: make markdownlint
+
+  check-crd-docs:
+    name: Check CRD auto-generated docs
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+
+      - name: Set up Go 1.x
+        uses: actions/setup-go@v3
+        with:
+          go-version: ${{ env.GO_VERSION }}
+
+      - name: Copy old docs
+        run: |
+          cp -R ./docs/content/en/docs/crd-ref ./docs/content/en/docs/crd-ref-old
+
+      - name: Run docs generator
+        run: ./.github/scripts/generate-crd-docs/generate-crd-docs.sh
+
+      - name: Check if docs are up to date
+        run: |
+          if ! diff -rq ./docs/content/en/docs/crd-ref ./docs/content/en/docs/crd-ref-old &>/dev/null; then
+            echo "The CRD docs have changes that are not reflected in the docs pages. Please use ./.github/scripts/generate-crd-docs/generate-crd-docs.sh to re-generate the docs."
+            echo ""
+            echo "=========== Diff ==========="
+            diff -ru ./docs/content/en/docs/crd-ref ./docs/content/en/docs/crd-ref-old
+            exit 1
+          else
+            echo ""
+            echo "CRD docs are up to date!"
+          fi

docs/content/en/docs/crd-ref/_index.md

@@ -1,5 +1,5 @@
 ---
-title: CRD Reference pages
+title: API Reference
 description: Reference information about the KLT CRDs
 weight: 100
 hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html

docs/content/en/docs/crd-ref/lifecycle/_index.md

@@ -0,0 +1,4 @@
+---
+title: Lifecycle API
+description: Reference information about the Lifecycle API
+---