docs: separate dev and user docs (#5114)

* docs: separate dev and user docs

Signed-off-by: Charles-Edouard Brétéché <charles.edouard@nirmata.com>

* fix

Signed-off-by: Charles-Edouard Brétéché <charles.edouard@nirmata.com>

* fix

Signed-off-by: Charles-Edouard Brétéché <charles.edouard@nirmata.com>

* fix

Signed-off-by: Charles-Edouard Brétéché <charles.edouard@nirmata.com>

Signed-off-by: Charles-Edouard Brétéché <charles.edouard@nirmata.com>

Makefile

@@ -427,11 +427,12 @@ codegen-deepcopy-all: codegen-deepcopy-kyverno codegen-deepcopy-report ## Genera
 .PHONY: codegen-api-docs
 codegen-api-docs: $(PACKAGE_SHIM) $(GEN_CRD_API_REFERENCE_DOCS) ## Generate API docs
 	@echo Generate api docs... >&2
-	@rm -rf docs/crd && mkdir -p docs/crd
+	@rm -rf docs/user/crd && mkdir -p docs/user/crd
-	@GOPATH=$(GOPATH_SHIM) $(GEN_CRD_API_REFERENCE_DOCS) -v 6 -api-dir ./api/kyverno/v1alpha2 -config docs/config.json -template-dir docs/template -out-file docs/crd/v1alpha2/index.html
+	@GOPATH=$(GOPATH_SHIM) $(GEN_CRD_API_REFERENCE_DOCS) -v 4 \
-	@GOPATH=$(GOPATH_SHIM) $(GEN_CRD_API_REFERENCE_DOCS) -v 6 -api-dir ./api/kyverno/v1beta1 -config docs/config.json -template-dir docs/template -out-file docs/crd/v1beta1/index.html
+			-api-dir github.com/kyverno/kyverno/api \
-	@GOPATH=$(GOPATH_SHIM) $(GEN_CRD_API_REFERENCE_DOCS) -v 6 -api-dir ./api/kyverno/v1 -config docs/config.json -template-dir docs/template -out-file docs/crd/v1/index.html
+			-config docs/user/config.json \
-	@GOPATH=$(GOPATH_SHIM) $(GEN_CRD_API_REFERENCE_DOCS) -v 6 -api-dir ./api/kyverno/v2beta1 -config docs/config.json -template-dir docs/template -out-file docs/crd/v2beta1/index.html
+			-template-dir docs/user/template \
+			-out-file docs/user/crd/index.html
 
 .PHONY: codegen-helm-docs
 codegen-helm-docs: ## Generate helm docs
@@ -517,10 +518,10 @@ verify-deepcopy: codegen-deepcopy-all ## Check deepcopy functions are up to date
 
 .PHONY: verify-api-docs
 verify-api-docs: codegen-api-docs ## Check api reference docs are up to date
-	@git --no-pager diff docs
+	@git --no-pager diff docs/user
 	@echo 'If this test fails, it is because the git diff is non-empty after running "make codegen-api-docs".' >&2
 	@echo 'To correct this, locally run "make codegen-api-docs", commit the changes, and re-run tests.' >&2
-	@git diff --quiet --exit-code docs
+	@git diff --quiet --exit-code docs/user
 
 .PHONY: verify-helm
 verify-helm: codegen-helm-all ## Check Helm charts are up to date

api/doc.go

@@ -0,0 +1 @@
+package api

api/policyreport/register.go

@@ -1,6 +1,5 @@
 package policyreport
 
 const (
-	// GroupName must be the same as specified in Policy CRD
 	GroupName = "wgpolicyk8s.io"
 )

api/policyreport/v1alpha2/common.go

@@ -68,23 +68,24 @@ func (prs PolicyReportSummary) ToMap() map[string]interface{} {
 	return m
 }
 
+// +kubebuilder:validation:Enum=pass;fail;warn;error;skip
+
 // PolicyResult has one of the following values:
 //   - pass: indicates that the policy requirements are met
 //   - fail: indicates that the policy requirements are not met
 //   - warn: indicates that the policy requirements and not met, and the policy is not scored
 //   - error: indicates that the policy could not be evaluated
 //   - skip: indicates that the policy was not selected based on user inputs or applicability
-//
-// +kubebuilder:validation:Enum=pass;fail;warn;error;skip
 type PolicyResult string
 
+// +kubebuilder:validation:Enum=critical;high;low;medium;info
+
 // PolicySeverity has one of the following values:
 // - critical
 // - high
 // - low
 // - medium
 // - info
-// +kubebuilder:validation:Enum=critical;high;low;medium;info
 type PolicySeverity string
 
 // PolicyReportResult provides the result for an individual policy

api/policyreport/v1alpha2/doc.go

@@ -14,8 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// Package v1alpha2 contains API Schema definitions for the policy v1alpha2 API group
 // +k8s:deepcopy-gen=package
-// +kubebuilder:object:generate=true
 // +groupName=wgpolicyk8s.io
+
 package v1alpha2

api/policyreport/v1alpha2/register.go

@@ -14,9 +14,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// Package v1alpha2 contains API Schema definitions for the policy v1alpha2 API group
-// +kubebuilder:object:generate=true
-// +groupName=wgpolicyk8s.io
 package v1alpha2
 
 import (

docs/README.md

@@ -6,22 +6,8 @@ This folder containers the generated CRD documentation in HTML format. It is ref
 
 Follow these steps to generate the docs:
 
-1. Install [gen-crd-api-reference-docs](https://github.com/ahmetb/gen-crd-api-reference-docs)
+1. Run `make codegen-api-docs`
 
-```shell
+2. Commit / push the results to git
-clone https://github.com/ahmetb/gen-crd-api-reference-docs
-cd gen-crd-api-reference-docs
-go build
-mv gen-crd-api-reference-docs $GOPATH/bin
-```
-
-2. Generate the HTML
-
-```shell
-gen-crd-api-reference-docs -api-dir ./pkg/api/kyverno/v1 \
-    -config docs/config.json  \
-    -template-dir docs/template/ \
-    -out-file docs/crd/v1/index.html
-```
 
 3. If needed, update the [docs site](https://kyverno.io/docs/crds/).

docs/user/README.md

@@ -0,0 +1,13 @@
+# docs
+
+This folder containers the generated CRD documentation in HTML format. It is referenced from the Kyverno website (https://kyverno.io/docs/crds/).
+
+## Building
+
+Follow these steps to generate the docs:
+
+1. Run `make codegen-api-docs`
+
+2. Commit / push the results to git
+
+3. If needed, update the [docs site](https://kyverno.io/docs/crds/).

docs/user/config.json

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

docs/user/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 class="table table-striped">
+            {{ template "members" .Type }}
+        </table>
+    {{ end }}
+    </td>
+</tr>
+{{ end }}
+{{ end }}
+
+{{ end }}

docs/user/template/pkg.tpl

@@ -0,0 +1,75 @@
+{{ define "packages" }}
+<!doctype html>
+<html lang="en">
+
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+
+    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" crossorigin="anonymous">
+    <title>Kyverno API</title>
+<style>
+    .bg-blue {
+        color: #ffffff;
+        background-color: #1589dd;
+    }
+</style>
+</head>
+
+<body>
+
+<div class="container">
+{{ with .packages}}
+<nav class="navbar navbar-expand-lg navbar-dark bg-dark">
+    <a class="navbar-brand" href="#"><p><b>Packages : </b></p></a>
+    <ul style="list-style:none">
+        {{ range . }}
+        <li>
+            <a href="#{{- packageAnchorID . -}}"><b style="color: white">{{ packageDisplayName . }}</b></a>
+        </li>
+        {{ end }}
+    </ul>
+</nav>
+{{ 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>
+    <hr />
+
+    {{ range (visibleTypes (sortedTypes .Types))}}
+        {{ template "type" .  }}
+    {{ end }}
+
+{{ end }}
+
+</div>
+
+<script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.min.js" integrity="sha384-UO2eT0CpHqdSJQ6hJty5KVphtPhzWj9WO1clHTMGa3JDZwrnQq4sF86dIHNDz0W1" crossorigin="anonymous"></script>
+<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js" integrity="sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM" crossorigin="anonymous"></script>
+
+</body>
+</html>
+
+{{ end }}

docs/user/template/type.tpl

@@ -0,0 +1,59 @@
+{{ 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>
+
+{{ if .Members }}
+<table class="table table-striped">
+    <thead class="thead-dark">
+        <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>
+<hr />
+{{ end }}
+
+{{ end }}