Auto-generate CRD Documentation #1342 (#1727)

* created documentation * Auto-generation of API CRD documentation Added the command in make docs now so when make docs command is ran, the API CRD documentation is also created automatically with "API.md" name, created a folder called template which contains all the necessary files (template files, place-holder go file, json file and executable binary file) which are used/needed in the creating of the API CRD documentation Signed-off-by: Kartik-Garg <[email protected]> * Auto-Generation of API CRD documentation Added the command in make docs now so when make docs command is ran, the API CRD documentation is also created automatically with "API.md" name, created a folder called template which contains all the necessary files (template files, place-holder go file, json file and executable binary file) which are used/needed in the creating of the API CRD documentation Signed-off-by: Kartik-Garg <[email protected]> * Deleting the directory * adding template folder for internal PR * Update Makefile Co-authored-by: kale-amruta <[email protected]> * Modifying dokcer build image Added tool to create CRD documentation to the docker build file, so we dont have to explicitly add exec binary to our project Signed-off-by: Kartik-Garg <[email protected]> * Removing executable binary and json from template folder As per the suggestion from the PR comment, removed executable binary from this folder, also removed .json file which was not required Signed-off-by: Kartik-Garg <[email protected]> * Changes in makefile Added a new target for creating on crd documentaion called as crd_docs and also added new command for it which is run inside the container image build Signed-off-by: Kartik-Garg <[email protected]> * Update Makefile Removed unwanted space Co-authored-by: Prasad Ghangal <[email protected]> * Update Makefile Improved the spacing as per the suggestion. Co-authored-by: Prasad Ghangal <[email protected]> * Making it more tidy Removed the template folder, updated API.md file, Made alignment changes Signed-off-by: Kartik-Garg <[email protected]> * Modifying makefile alignement Modified space in makefile Signed-off-by: Kartik-Garg <[email protected]> * Made changes in the Dockerfile build and makfile Added new required files for the API CRD documentation tool and made changes in the docker build and the makefile command to run the target to generate the documentation. Changed config file name. Signed-off-by: Kartik-Garg <[email protected]> * Changes in CONTRIBUTING.md Added steps to create the documentation when changes are made in Kanister API Types as well. Signed-off-by: Kartik-Garg <[email protected]> --------- Signed-off-by: Kartik-Garg <[email protected]> Signed-off-by: Kartik-Garg <[email protected]> Co-authored-by: kale-amruta <[email protected]> Co-authored-by: Prasad Ghangal <[email protected]>
kanisterio · Feb 22, 2023 · f448a96 · f448a96
1 parent c29b06c
commit f448a96
Show file tree

Hide file tree

Showing 8 changed files with 1,701 additions and 0 deletions.
diff --git a/API.md b/API.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -77,6 +77,10 @@ styling and safety rules.
 See the [BUILD.md](BUILD.md) document for instructions on how to build, test and
 run Kanister locally.
 
+### Updating the API types
+
+If your changes involve the Kanister API types, generate the API documentation using the `make crd_docs` command and push the updated `API.md` file along with any other changes.
+
 ### Commit messages
 
 The basic idea is that we ask all contributors to practice

diff --git a/Makefile b/Makefile
@@ -204,6 +204,27 @@ else
 	@/bin/bash -c $(DOCS_CMD)
 endif
 
+API_DOCS_CMD = "gen-crd-api-reference-docs 			\
+		-config docs/api_docs/config.json 	\
+		-api-dir ./pkg/apis/cr/v1alpha1 	\
+		-template-dir docs/api_docs/template 		\
+		-out-file API.md 	\
+"
+
+crd_docs:
+ifeq ($(DOCKER_BUILD),"true")
+	@echo "running API_DOCS_CMD in the containerized build environment"
+	@docker run             \
+		--entrypoint ''     \
+		--rm                \
+		-v "$(PWD):/repo"   \
+		-w /repo            \
+		$(BUILD_IMAGE) \
+		/bin/bash -c $(API_DOCS_CMD)
+else
+	@/bin/bash -c $(API_DOCS_CMD)
+endif
+
 build-dirs:
 	@mkdir -p bin/$(ARCH)
 	@mkdir -p .go/src/$(PKG) .go/pkg .go/bin .go/std/$(ARCH)

diff --git a/docker/build/Dockerfile b/docker/build/Dockerfile
@@ -22,6 +22,9 @@ COPY --from=golangci/golangci-lint:v1.50 /usr/bin/golangci-lint /usr/local/bin/
 RUN wget -O /usr/local/bin/kind https://github.com/kubernetes-sigs/kind/releases/download/v0.11.1/kind-linux-amd64 \
     && chmod +x /usr/local/bin/kind
 
+# Adding CRD documentation generation tool.
+RUN GOBIN=/usr/local/bin go install github.com/ahmetb/[email protected]
+
 ENV CGO_ENABLED=0 \
     GO111MODULE="on" \
     GOROOT="/usr/local/go" \

diff --git a/docs/api_docs/config.json b/docs/api_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://v1-18.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#{{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
+}
diff --git a/docs/api_docs/template/members.tpl b/docs/api_docs/template/members.tpl
@@ -0,0 +1,50 @@
+{*Refering this file from https://github.com/ahmetb/gen-crd-api-reference-docs/ which is used in auto-generation of API CRD documentation.*}
+
+{{ 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 }}
diff --git a/docs/api_docs/template/pkg.tpl b/docs/api_docs/template/pkg.tpl
@@ -0,0 +1,51 @@
+{*Refering this file from https://github.com/ahmetb/gen-crd-api-reference-docs/ which is used in auto-generation of API CRD documentation.*}
+
+{{ 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 }}
+        <p>
+            {{ safe (renderComments .) }}
+        </p>
+        {{ 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 }}
diff --git a/docs/api_docs/template/type.tpl b/docs/api_docs/template/type.tpl
@@ -0,0 +1,83 @@
+{*Refering this file from https://github.com/ahmetb/gen-crd-api-reference-docs/ which is used in auto-generation of API CRD documentation.*}
+
+{{ define "type" }}
+
+<h3 id="{{ anchorIDForType . }}">
+    {{- .Name.Name }}
+    {{ if eq .Kind "Alias" }}(<code>{{.Underlying}}</code> alias)</p>{{ end -}}
+</h3>
+{{ with (typeReferences .) }}
+    <p>
+        (<em>Appears on:</em>
+        {{- $prev := "" -}}
+        {{- range . -}}
+            {{- if $prev -}}, {{ end -}}
+            {{ $prev = . }}
+            <a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
+        {{- end -}}
+        )
+    </p>
+{{ end }}
+
+<p>
+    {{ safe (renderComments .CommentLines) }}
+</p>
+
+{{ 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 }}