diff --git a/Makefile b/Makefile index c327e0e6fc7..c3d867563cd 100644 --- a/Makefile +++ b/Makefile @@ -204,12 +204,12 @@ else @/bin/bash -c $(DOCS_CMD) endif -API_DOCS_CMD = "gen-crd-api-reference-docs \ - -config /usr/local/bin/example-config.json \ - -api-dir ./pkg/apis/cr/v1alpha1 \ - -template-dir /usr/local/bin/template \ - -out-file API.md \ - " +API_DOCS_CMD = "gen-crd-api-reference-docs \ + -config docs/api_docs/example-config.json \ + -api-dir ./pkg/apis/cr/v1alpha1 \ + -template-dir docs/api_docs/template \ + -out-file API.md \ +" crd_docs: ifeq ($(DOCKER_BUILD),"true") diff --git a/docker/build/Dockerfile b/docker/build/Dockerfile index c4553c68d67..014e3d8b2c1 100644 --- a/docker/build/Dockerfile +++ b/docker/build/Dockerfile @@ -22,14 +22,8 @@ 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 tool here, since docs-build does not have golang base to create binary from go file -RUN wget -O gen-crd-api-reference-docs_linux_amd64.tar.gz https://github.com/ahmetb/gen-crd-api-reference-docs/archive/refs/tags/v0.3.0.tar.gz \ - && tar xzfv gen-crd-api-reference-docs_linux_amd64.tar.gz \ - && mkdir crd_documentation \ - && cp -r gen-crd-api-reference-docs-0.3.0/* ./crd_documentation \ - && cd crd_documentation \ - && go build \ - && cp -r * /usr/local/bin/ +# Adding CRD documentation generation tool. +RUN GOBIN=/usr/local/bin go install github.com/ahmetb/gen-crd-api-reference-docs@v0.3.0 ENV CGO_ENABLED=0 \ GO111MODULE="on" \ diff --git a/docs/api_docs/example-config.json b/docs/api_docs/example-config.json new file mode 100644 index 00000000000..298f00b64cc --- /dev/null +++ b/docs/api_docs/example-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 new file mode 100644 index 00000000000..a529c671647 --- /dev/null +++ b/docs/api_docs/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/docs/api_docs/template/pkg.tpl b/docs/api_docs/template/pkg.tpl new file mode 100644 index 00000000000..2f03a803b61 --- /dev/null +++ b/docs/api_docs/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/docs/api_docs/template/type.tpl b/docs/api_docs/template/type.tpl new file mode 100644 index 00000000000..f1babcbdc5e --- /dev/null +++ b/docs/api_docs/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 }}