From 0e2baf38e46a0f9c48c5fcd07ca73ae10d12755b Mon Sep 17 00:00:00 2001 From: Sean Eagan Date: Thu, 21 Jan 2021 12:56:46 -0600 Subject: [PATCH] Generate api docs for CRD types Change-Id: I803689985c0010b452f52bfe9a57bc5e910d051f Signed-off-by: Sean Eagan --- Makefile | 23 +- docs/api/vino.md | 870 +++++++++++++++++++++++++++++ hack/api-docs/config.json | 33 ++ hack/api-docs/template/members.tpl | 46 ++ hack/api-docs/template/pkg.tpl | 46 ++ hack/api-docs/template/type.tpl | 60 ++ pkg/api/v1/doc.go | 20 + pkg/api/v1/groupversion_info.go | 3 - pkg/api/v1/vino_types.go | 2 +- tools/whitespace_linter | 2 +- 10 files changed, 1099 insertions(+), 6 deletions(-) create mode 100644 docs/api/vino.md create mode 100644 hack/api-docs/config.json create mode 100644 hack/api-docs/template/members.tpl create mode 100644 hack/api-docs/template/pkg.tpl create mode 100644 hack/api-docs/template/type.tpl create mode 100644 pkg/api/v1/doc.go diff --git a/Makefile b/Makefile index dd40391..06ca89c 100644 --- a/Makefile +++ b/Makefile @@ -8,6 +8,7 @@ CRD_OPTIONS ?= "crd:trivialVersions=true" TOOLBINDIR := tools/bin +API_REF_GEN_VERSION = v0.3.0 CONTROLLER_GEN_VERSION = v0.3.0 # linting @@ -29,7 +30,7 @@ DOCKER_PROXY_FLAGS += --build-arg NO_PROXY=$(NO_PROXY) all: manager # Run tests -test: generate fmt vet manifests lint +test: generate fmt vet manifests lint api-docs go test ./... -coverprofile cover.out # Build manager binary @@ -85,6 +86,26 @@ docker-push-controller: docker-push-nodelabeler: docker push ${NODE_LABELER_IMG} +# Generate API reference documentation +api-docs: gen-crd-api-reference-docs + $(API_REF_GEN) -api-dir=./pkg/api/v1 -config=./hack/api-docs/config.json -template-dir=./hack/api-docs/template -out-file=./docs/api/vino.md + +API_REF_GEN=$(GOBIN)/gen-crd-api-reference-docs + +# Find or download gen-crd-api-reference-docs +gen-crd-api-reference-docs: + @{ \ + if ! which $(API_REF_GEN);\ + then\ + set -e ;\ + API_REF_GEN_TMP_DIR=$$(mktemp -d) ;\ + cd $$API_REF_GEN_TMP_DIR ;\ + go mod init tmp ;\ + go get github.com/ahmetb/gen-crd-api-reference-docs@$(API_REF_GEN_VERSION) ;\ + rm -rf $$API_REF_GEN_TMP_DIR ;\ + fi;\ + } + CONTROLLER_GEN:=$(GOBIN)/controller-gen # find or download controller-gen diff --git a/docs/api/vino.md b/docs/api/vino.md new file mode 100644 index 0000000..2c674de --- /dev/null +++ b/docs/api/vino.md @@ -0,0 +1,870 @@ +

Vino API reference

+

Packages:

+ +

airship.airshipit.org/v1

+

Package v1 contains API Schema definitions for the airship v1 API group

+Resource Types: + +

CPUConfiguration +

+

+(Appears on: +VinoSpec) +

+

CPUConfiguration CPU node configuration

+
+
+ + + + + + + + + + + + + +
FieldDescription
+cpuExclude
+ +string + +		 +

Exclude CPU example 0-4,54-60

+
+
+
+

DaemonSetOptions +

+

+(Appears on: +VinoSpec) +

+

DaemonSetOptions be used to spawn vino-builder, libvirt, sushy an

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+namespacedName
+ + +NamespacedName + + +		 +
+libvirtImage
+ +string + +		 +
+sushyImage
+ +string + +		 +
+vinoBuilderImage
+ +string + +		 +
+nodeAnnotatorImage
+ +string + +		 +
+
+
+

DiskDrivesTemplate +

+

+(Appears on: +NodeSet) +

+

DiskDrivesTemplate defines disks on the VM

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+name
+ +string + +		 +
+type
+ +string + +		 +
+path
+ +string + +		 +
+options
+ + +DiskOptions + + +		 +
+
+
+

DiskOptions +

+

+(Appears on: +DiskDrivesTemplate) +

+

DiskOptions disk options

+
+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+sizeGb
+ +int + +		 +
+sparse
+ +bool + +		 +
+
+
+

NamespacedName +

+

+(Appears on: +DaemonSetOptions, +NodeSet) +

+

NamespacedName to be used to spawn VMs

+
+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+name
+ +string + +		 +
+namespace
+ +string + +		 +
+
+
+

Network +

+

+(Appears on: +VinoSpec) +

+

Network defines libvirt networks

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+name
+ +string + +		 +

Network Parameter defined

+
+subnet
+ +string + +		 +
+allocationStart
+ +string + +		 +
+allocationStop
+ +string + +		 +
+dns_servers
+ +[]string + +		 +
+routes
+ + +VMRoutes + + +		 +
+
+
+

NetworkInterface +

+

+(Appears on: +NodeSet) +

+

NetworkInterface define interface on the VM

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+name
+ +string + +		 +

Define parameter for network interfaces

+
+type
+ +string + +		 +
+network
+ +string + +		 +
+mtu
+ +int + +		 +
+options
+ +map[string]string + +		 +
+
+
+

NodeSelector +

+

+(Appears on: +VinoSpec) +

+

NodeSelector identifies nodes to create VMs on

+
+
+ + + + + + + + + + + + + +
FieldDescription
+matchLabels
+ +map[string]string + +		 +

Node type needs to specified

+
+
+
+

NodeSet +

+

+(Appears on: +VinoSpec) +

+

NodeSet node definitions

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+name
+ +string + +		 +

Parameter for Node master or worker-standard

+
+count
+ +int + +		 +
+labels
+ + +VMNodeFlavor + + +		 +
+libvirtTemplate
+ + +NamespacedName + + +		 +
+networkInterfaces
+ + +NetworkInterface + + +		 +
+diskDrives
+ + +DiskDrivesTemplate + + +		 +
+
+
+

VMNodeFlavor +

+

+(Appears on: +NodeSet) +

+

VMNodeFlavor labels for node to be annotated

+
+
+ + + + + + + + + + + + + +
FieldDescription
+vmFlavor
+ +map[string]string + +		 +
+
+
+

VMRoutes +

+

+(Appears on: +Network) +

+

VMRoutes defined

+
+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+to
+ +string + +		 +
+via
+ +string + +		 +
+
+
+

Vino +

+

Vino is the Schema for the vinoes API

+
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+metadata
+ + +Kubernetes meta/v1.ObjectMeta + + +		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
+spec
+ + +VinoSpec + + +		 +
+
+ + + + + + + + + + + + + + + + + + + + + +
+nodeSelector
+ + +NodeSelector + + +		 +

Define nodelabel parameters

+
+configuration
+ + +CPUConfiguration + + +		 +

Define CPU configuration

+
+networks
+ + +Network + + +		 +

Define network parameters

+
+nodes
+ + +[]NodeSet + + +		 +

Define node details

+
+daemonSetOptions
+ + +DaemonSetOptions + + +		 +

DaemonSetOptions defines how vino will spawn daemonset on nodes

+
+
+status
+ + +VinoStatus + + +		 +
+
+
+

VinoSpec +

+

+(Appears on: +Vino) +

+

VinoSpec defines the desired state of Vino

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+nodeSelector
+ + +NodeSelector + + +		 +

Define nodelabel parameters

+
+configuration
+ + +CPUConfiguration + + +		 +

Define CPU configuration

+
+networks
+ + +Network + + +		 +

Define network parameters

+
+nodes
+ + +[]NodeSet + + +		 +

Define node details

+
+daemonSetOptions
+ + +DaemonSetOptions + + +		 +

DaemonSetOptions defines how vino will spawn daemonset on nodes

+
+
+
+

VinoStatus +

+

+(Appears on: +Vino) +

+

VinoStatus defines the observed state of Vino

+
+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+configMapRef
+ + +Kubernetes core/v1.ObjectReference + + +		 +
+conditions
+ + +[]Kubernetes meta/v1.Condition + + +		 +
+
+
+
+

This page was automatically generated with gen-crd-api-reference-docs

+
diff --git a/hack/api-docs/config.json b/hack/api-docs/config.json new file mode 100644 index 0000000..85f9b2f --- /dev/null +++ b/hack/api-docs/config.json @@ -0,0 +1,33 @@ +{ + "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/apiextensions-apiserver/pkg/apis/apiextensions/v1\\.JSON$", + "docsURLTemplate": "https://pkg.go.dev/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1?tab=doc#JSON" + }, + { + "typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis)/", + "docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}" + }, + { + "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Condition$", + "docsURLTemplate": "https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Condition" + } + ], + "typeDisplayNamePrefixOverrides": { + "k8s.io/api/": "Kubernetes ", + "k8s.io/apimachinery/pkg/apis/": "Kubernetes ", + "k8s.io/apiextensions-apiserver/": "Kubernetes " + }, + "markdownDisabled": false +} diff --git a/hack/api-docs/template/members.tpl b/hack/api-docs/template/members.tpl new file mode 100644 index 0000000..26e7251 --- /dev/null +++ b/hack/api-docs/template/members.tpl @@ -0,0 +1,46 @@ +{{ 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/hack/api-docs/template/pkg.tpl b/hack/api-docs/template/pkg.tpl new file mode 100644 index 0000000..5713d98 --- /dev/null +++ b/hack/api-docs/template/pkg.tpl @@ -0,0 +1,46 @@ +{{ define "packages" }} +

Vino API reference

+ + {{ 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 }} + +
+

This page was automatically generated with gen-crd-api-reference-docs

+
+{{ end }} diff --git a/hack/api-docs/template/type.tpl b/hack/api-docs/template/type.tpl new file mode 100644 index 0000000..cd2fa69 --- /dev/null +++ b/hack/api-docs/template/type.tpl @@ -0,0 +1,60 @@ +{{ define "type" }} +

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

+ + {{ with (typeReferences .) }} +

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

+ {{ end }} + + {{ with .CommentLines }} + {{ safe (renderComments .) }} + {{ end }} + + {{ if .Members }} +
+
+ + + + + + + + + {{ if isExportedType . }} + + + + + + + + + {{ end }} + {{ template "members" . }} + +
FieldDescription
+ apiVersion
+ string		 + {{ apiGroup . }} +
+ kind
+ string + 		+ {{ .Name.Name }} +
+
+
+ {{ end }} +{{ end }} diff --git a/pkg/api/v1/doc.go b/pkg/api/v1/doc.go new file mode 100644 index 0000000..80dcdba --- /dev/null +++ b/pkg/api/v1/doc.go @@ -0,0 +1,20 @@ +/* + + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Package v1 contains API Schema definitions for the airship v1 API group +// +kubebuilder:object:generate=true +// +groupName=airship.airshipit.org +package v1 diff --git a/pkg/api/v1/groupversion_info.go b/pkg/api/v1/groupversion_info.go index 55462d0..27762a2 100644 --- a/pkg/api/v1/groupversion_info.go +++ b/pkg/api/v1/groupversion_info.go @@ -14,9 +14,6 @@ See the License for the specific language governing permissions and limitations under the License. */ -// Package v1 contains API Schema definitions for the airship v1 API group -// +kubebuilder:object:generate=true -// +groupName=airship.airshipit.org package v1 import ( diff --git a/pkg/api/v1/vino_types.go b/pkg/api/v1/vino_types.go index 48b5822..eaad9cf 100644 --- a/pkg/api/v1/vino_types.go +++ b/pkg/api/v1/vino_types.go @@ -132,9 +132,9 @@ type DiskOptions struct { } // +kubebuilder:object:root=true +// +kubebuilder:subresource:status // Vino is the Schema for the vinoes API -// +kubebuilder:subresource:status type Vino struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` diff --git a/tools/whitespace_linter b/tools/whitespace_linter index 280cef5..aa73e1f 100755 --- a/tools/whitespace_linter +++ b/tools/whitespace_linter @@ -2,7 +2,7 @@ # git 1.9.0+ allows for exclusions in pathspecs via ':!foo' syntax. # However, until git 2.13.0 there must be at least one "inclusive" pathspec, hence the './*' -trailing_whitespace=$(git grep -E -n -- ' +$' -- './*' ':!*.png') +trailing_whitespace=$(git grep -E -n -- ' +$' -- './*' ':!*.png' ':!docs/api/vino.md') if [[ -n "$trailing_whitespace" ]]; then printf "ERROR: Trailing whitespaces:\n"