Merge pull request #71 from rabbitmq/api-docs

Add API docs

.github/workflows/publish-versioned-api-ref.yml

@@ -0,0 +1,45 @@
+name: "Publish Versioned API Reference Wiki page"
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+
+jobs:
+  publish-versioned-api-reference:
+    name: Publish Versioned API Reference Wiki
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout operator codebase
+        uses: actions/checkout@v2
+        with:
+          path: messaging-topology-operator
+      - name: Get the version
+        id: get_version
+        run: echo ::set-output name=VERSION::${GITHUB_REF/refs\/tags\//}
+      - name: Checkout wiki codebase
+        uses: actions/checkout@v2
+        with:
+          repository: ${{ github.repository }}.wiki
+          path: wiki
+      - name: Push to wiki
+        run: |
+          cd wiki
+          git config --local user.email "github-actions@github.com"
+          git config --local user.name "github-actions"
+          # Add the versioned API Reference to the Wiki
+          cp ../messaging-topology-operator/docs/api/rabbitmq.com.ref.asciidoc ./API_Reference_${{ steps.get_version.outputs.VERSION }}.asciidoc
+          # Regenerate the ordered list of API Reference docs for the sidebar
+          export REGENERATED_SIDEBAR="$(../messaging-topology-operator/hack/generate-ordered-api-reference-list.sh .)"
+          echo "$REGENERATED_SIDEBAR" > Wiki_Sidebar.md
+          git add ./API_Reference_${{ steps.get_version.outputs.VERSION }}.asciidoc
+          git add ./Wiki_Sidebar.md
+          git commit -m "Publish version ${{ steps.get_version.outputs.VERSION }} API Reference" && git push
+      - uses: 8398a7/action-slack@v3
+        with:
+          status: ${{ job.status }}
+          fields: repo,message,action,eventName
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+        if: failure()

.github/workflows/update-latest-api-ref.yml

@@ -0,0 +1,37 @@
+name: "Update Latest API Reference Wiki page"
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  update-api-reference:
+    name: Update Latest API Reference Wiki
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout operator codebase
+        uses: actions/checkout@v2
+        with:
+          path: messaging-topology-operator
+      - name: Checkout wiki codebase
+        uses: actions/checkout@v2
+        with:
+          repository: ${{ github.repository }}.wiki
+          path: wiki
+      - name: Push to wiki
+        run: |
+          cd wiki
+          git config --local user.email "github-actions@github.com"
+          git config --local user.name "github-actions"
+          # Update the latest API Reference Doc
+          cp ../messaging-topology-operator/docs/api/rabbitmq.com.ref.asciidoc ./API_Reference.asciidoc
+          git add ./API_Reference.asciidoc
+          git diff-index --quiet HEAD || git commit -m "Update Latest API Reference" && git push
+      - uses: 8398a7/action-slack@v3
+        with:
+          status: ${{ job.status }}
+          fields: repo,message,action,eventName
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+        if: failure()

Makefile

@@ -61,6 +61,15 @@ deploy-rbac:
 manifests: install-tools
 	controller-gen $(CRD_OPTIONS) rbac:roleName=manager-role webhook paths="./..." output:crd:artifacts:config=config/crd/bases
 
+# Generate API reference documentation
+api-reference:
+	crd-ref-docs \
+		--source-path ./api/v1alpha1 \
+		--config ./docs/api/autogen/config.yaml \
+		--templates-dir ./docs/api/autogen/templates \
+		--output-path ./docs/api/rabbitmq.com.ref.asciidoc \
+		--max-depth 30
+
 # Run go fmt against code
 fmt:
 	go fmt ./...
@@ -69,8 +78,8 @@ fmt:
 vet:
 	go vet ./...
 
-# Generate code
-generate: install-tools
+# Generate code & docs
+generate: install-tools api-reference
 	controller-gen object:headerFile="hack/NOTICE.go.txt" paths="./..."
 
 check-env-docker-credentials: check-env-registry-server

docs/api/autogen/config.yaml

@@ -0,0 +1,2 @@
+render:
+  kubernetesVersion: "1.20"

docs/api/autogen/templates/gv_details.tpl

@@ -0,0 +1,20 @@
+{{- define "gvDetails" -}}
+{{- $gv := . -}}
+[id="{{ asciidocGroupVersionID $gv | asciidocRenderAnchorID }}"]
+== {{ $gv.GroupVersionString }}
+
+{{ $gv.Doc }}
+
+{{- if $gv.Kinds  }}
+.Resource Types
+{{- range $gv.SortedKinds }}
+- {{ $gv.TypeForKind . | asciidocRenderTypeLink }}
+{{- end }}
+{{ end }}
+
+=== Definitions
+{{ range $gv.SortedTypes }}
+{{ template "type" . }}
+{{ end }}
+
+{{- end -}}

docs/api/autogen/templates/gv_list.tpl

@@ -0,0 +1,19 @@
+{{- define "gvList" -}}
+{{- $groupVersions := . -}}
+
+// Generated documentation. Please do not edit.
+:anchor_prefix: k8s-api
+
+[id="{p}-api-reference"]
+= API Reference
+
+.Packages
+{{- range $groupVersions }}
+- {{ asciidocRenderGVLink . }}
+{{- end }}
+
+{{ range $groupVersions }}
+{{ template "gvDetails" . }}
+{{ end }}
+
+{{- end -}}

docs/api/autogen/templates/type.tpl

@@ -0,0 +1,35 @@
+{{- define "type" -}}
+{{- $type := . -}}
+{{- if asciidocShouldRenderType $type -}}
+
+[id="{{ asciidocTypeID $type | asciidocRenderAnchorID }}"]
+==== {{ $type.Name  }} {{ if $type.IsAlias }}({{ asciidocRenderTypeLink $type.UnderlyingType  }}) {{ end }}
+
+{{ $type.Doc }}
+
+{{ if $type.References -}}
+.Appears In:
+****
+{{- range $type.SortedReferences }}
+- {{ asciidocRenderTypeLink . }}
+{{- end }}
+****
+{{- end }}
+
+{{ if $type.Members -}}
+[cols="25a,75a", options="header"]
+|===
+| Field | Description
+{{ if $type.GVK -}}
+| *`apiVersion`* __string__ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}`
+| *`kind`* __string__ | `{{ $type.GVK.Kind }}`
+{{ end -}}
+
+{{ range $type.Members -}}
+| *`{{ .Name  }}`* __{{ asciidocRenderType .Type }}__ | {{ template "type_members" . }}
+{{ end -}}
+|===
+{{ end -}}
+
+{{- end -}}
+{{- end -}}

docs/api/autogen/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 -}}