Add some generated API documentation. (#81)

Add some generated API documentation using https://github.com/elastic/crd-ref-docs which is now packaged in the codegen image.

hack/lib/docs/config.yaml

@@ -0,0 +1,12 @@
+# Configuration file for https://github.com/elastic/crd-ref-docs
+processor:
+
+  #  Ignore internal API versions
+  ignoreGroupVersions:
+    - "crd.pinniped.dev/crdpinniped"
+    - "pinniped.dev/pinniped"
+  ignoreFields:
+    - "TypeMeta$"
+
+render:
+  kubernetesVersion: KUBE_MINOR_VERSION

hack/lib/docs/templates/gv_details.tpl

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

hack/lib/docs/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 -}}

hack/lib/docs/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 -}}

hack/lib/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 -}}

hack/lib/update-codegen.sh

@@ -66,6 +66,7 @@ echo "running in container to generate ${KUBE_VERSION} into ${OUTPUT_DIR}..."
 # variables in the template files and renaming them to strip the `.tmpl` extension.
 cp -R "${ROOT}/apis" "${OUTPUT_DIR}/apis"
 find "${OUTPUT_DIR}" -type f -exec sed -i "s|GENERATED_PKG|generated/${KUBE_MINOR_VERSION}|g" {} \;
+find "${OUTPUT_DIR}" -type f -not -name '*.tmpl' -exec rm {} \;
 find "${OUTPUT_DIR}" -type f -name '*.tmpl' -exec bash -c 'mv "$0" "${0%.tmpl}"' {} \;
 
 # Make the generated API code its own Go module.
@@ -142,3 +143,12 @@ echo "generating client code for our public API groups..."
 # Tidy up the .../client module
 echo "tidying ${OUTPUT_DIR}/client/go.mod..."
 (cd client && go mod tidy 2>&1 | sed "s|^|go-mod-tidy > |")
+
+# Generate API documentation
+sed "s|KUBE_MINOR_VERSION|${KUBE_MINOR_VERSION}|g" < "${ROOT}/hack/lib/docs/config.yaml" > /tmp/docs-config.yaml
+crd-ref-docs \
+    --source-path="${ROOT}/generated/${KUBE_MINOR_VERSION}/apis" \
+    --config=/tmp/docs-config.yaml \
+    --renderer=asciidoctor \
+    --templates-dir="${ROOT}/hack/lib/docs/templates" \
+    --output-path="${ROOT}/generated/${KUBE_MINOR_VERSION}/README.adoc"