add CRD doc generator (#505)

docgen/.gitignore

@@ -0,0 +1,2 @@
+docs.html
+api-reference.md

docgen/README.md

@@ -0,0 +1,21 @@
+# Generate API Docs
+
+Install doc generator
+
+```sh
+go install github.com/ahmetb/gen-crd-api-reference-docs
+```
+
+Generate html docs
+
+``` sh
+cd docgen
+
+gen-crd-api-reference-docs -config config.json -api-dir "../pkg/apis/applicationnetworking/v1alpha1/" -out-file docs.html
+```
+
+Add generated content to template
+
+``` sh
+cat api-reference-base.md docs.html > ../docs/api-reference.md
+```

docgen/api-reference-base.md

@@ -0,0 +1,4 @@
+# API Reference
+
+This page contains the API field specification for Gateway API.
+

docgen/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
+}

docgen/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 }}

docgen/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 }}

docgen/template/placeholder.go

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

docgen/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 }}