From f60dd6c28f711f5d6ca91d6a1d08770fee86a703 Mon Sep 17 00:00:00 2001 From: Mikhail Berezovskiy Date: Wed, 15 Nov 2023 13:24:38 -0800 Subject: [PATCH] add CRD doc generator --- docgen/.gitignore | 2 + docgen/README.md | 21 +++++++++ docgen/api-reference-base.md | 4 ++ docgen/config.json | 28 ++++++++++++ docgen/template/members.tpl | 48 ++++++++++++++++++++ docgen/template/pkg.tpl | 49 ++++++++++++++++++++ docgen/template/placeholder.go | 2 + docgen/template/type.tpl | 81 ++++++++++++++++++++++++++++++++++ 8 files changed, 235 insertions(+) create mode 100644 docgen/.gitignore create mode 100644 docgen/README.md create mode 100644 docgen/api-reference-base.md create mode 100644 docgen/config.json create mode 100644 docgen/template/members.tpl create mode 100644 docgen/template/pkg.tpl create mode 100644 docgen/template/placeholder.go create mode 100644 docgen/template/type.tpl diff --git a/docgen/.gitignore b/docgen/.gitignore new file mode 100644 index 00000000..0bbbe0a4 --- /dev/null +++ b/docgen/.gitignore @@ -0,0 +1,2 @@ +docs.html +api-reference.md \ No newline at end of file diff --git a/docgen/README.md b/docgen/README.md new file mode 100644 index 00000000..c9d94353 --- /dev/null +++ b/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 +``` diff --git a/docgen/api-reference-base.md b/docgen/api-reference-base.md new file mode 100644 index 00000000..c1d93817 --- /dev/null +++ b/docgen/api-reference-base.md @@ -0,0 +1,4 @@ +# API Reference + +This page contains the API field specification for Gateway API. + diff --git a/docgen/config.json b/docgen/config.json new file mode 100644 index 00000000..f323323c --- /dev/null +++ b/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 +} diff --git a/docgen/template/members.tpl b/docgen/template/members.tpl new file mode 100644 index 00000000..a529c671 --- /dev/null +++ b/docgen/template/members.tpl @@ -0,0 +1,48 @@ +{{ define "members" }} + +{{ range .Members }} +{{ if not (hiddenMember .)}} + + + {{ fieldName . }}
+ + {{ if linkForType .Type }} + + {{ typeDisplayName .Type }} + + {{ else }} + {{ typeDisplayName .Type }} + {{ end }} + + + + {{ if fieldEmbedded . }} +

+ (Members of {{ fieldName . }} are embedded into this type.) +

+ {{ end}} + + {{ if isOptionalMember .}} + (Optional) + {{ end }} + + {{ safe (renderComments .CommentLines) }} + + {{ if and (eq (.Type.Name.Name) "ObjectMeta") }} + Refer to the Kubernetes API documentation for the fields of the + metadata field. + {{ end }} + + {{ if or (eq (fieldName .) "spec") }} +
+
+ + {{ template "members" .Type }} +
+ {{ end }} + + +{{ end }} +{{ end }} + +{{ end }} diff --git a/docgen/template/pkg.tpl b/docgen/template/pkg.tpl new file mode 100644 index 00000000..842ec93d --- /dev/null +++ b/docgen/template/pkg.tpl @@ -0,0 +1,49 @@ +{{ define "packages" }} + +{{ with .packages}} +

Packages:

+ +{{ end}} + +{{ range .packages }} +

+ {{- packageDisplayName . -}} +

+ + {{ with (index .GoPackages 0 )}} + {{ with .DocComments }} +
+ {{ safe (renderComments .) }} +
+ {{ end }} + {{ end }} + + Resource Types: + + + {{ range (visibleTypes (sortedTypes .Types))}} + {{ template "type" . }} + {{ end }} +
+{{ end }} + +

+ Generated with gen-crd-api-reference-docs + {{ with .gitCommit }} on git commit {{ . }}{{end}}. +

+ +{{ end }} diff --git a/docgen/template/placeholder.go b/docgen/template/placeholder.go new file mode 100644 index 00000000..cc8f1453 --- /dev/null +++ b/docgen/template/placeholder.go @@ -0,0 +1,2 @@ +// Placeholder file to make Go vendor this directory properly. +package template diff --git a/docgen/template/type.tpl b/docgen/template/type.tpl new file mode 100644 index 00000000..8f0d66b8 --- /dev/null +++ b/docgen/template/type.tpl @@ -0,0 +1,81 @@ +{{ define "type" }} + +

+ {{- .Name.Name }} + {{ if eq .Kind "Alias" }}({{.Underlying}} alias){{ end -}} +

+{{ with (typeReferences .) }} +

+ (Appears on: + {{- $prev := "" -}} + {{- range . -}} + {{- if $prev -}}, {{ end -}} + {{- $prev = . -}} + {{ typeDisplayName . }} + {{- end -}} + ) +

+{{ end }} + +
+ {{ safe (renderComments .CommentLines) }} +
+ +{{ with (constantsOfType .) }} + + + + + + + + + {{- range . -}} + + {{- /* + renderComments implicitly creates a

element, so we + add one to the display name as well to make the contents + of the two cells align evenly. + */ -}} +

+ + + {{- end -}} + +
ValueDescription

{{ typeDisplayName . }}

{{ safe (renderComments .CommentLines) }}
+{{ end }} + +{{ if .Members }} + + + + + + + + + {{ if isExportedType . }} + + + + + + + + + {{ end }} + {{ template "members" .}} + +
FieldDescription
+ apiVersion
+ string		 + + {{apiGroup .}} + +
+ kind
+ string + 		{{.Name.Name}}
+{{ end }} + +{{ end }}