From 89fbb94953f6b1e079091d4062e7728217231f6e Mon Sep 17 00:00:00 2001 From: Sean Eagan Date: Thu, 21 Jan 2021 13:50:43 -0600 Subject: [PATCH] Generate api docs for CRD types Signed-off-by: Sean Eagan Change-Id: I646579ed39f1b7bd2eefd34473d653cedbec9adf --- Makefile | 22 +- docs/api/sipcluster.md | 461 +++++++++++++++++++++++++++++ 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 - tools/whitespace_linter | 2 +- 9 files changed, 688 insertions(+), 5 deletions(-) create mode 100644 docs/api/sipcluster.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 397402c..d5544dc 100644 --- a/Makefile +++ b/Makefile @@ -38,7 +38,7 @@ kubernetes: 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 @@ -87,6 +87,26 @@ docker-build: docker-push: docker push ${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/sipcluster.md + +# Find or download gen-crd-api-reference-docs +gen-crd-api-reference-docs: +ifeq (, $(shell which gen-crd-api-reference-docs)) + @{ \ + 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@v0.2.0 ;\ + rm -rf $$API_REF_GEN_TMP_DIR ;\ + } +API_REF_GEN=$(GOBIN)/gen-crd-api-reference-docs +else +API_REF_GEN=$(shell which gen-crd-api-reference-docs) +endif + # find or download controller-gen # download controller-gen if necessary controller-gen: diff --git a/docs/api/sipcluster.md b/docs/api/sipcluster.md new file mode 100644 index 0000000..e638bf4 --- /dev/null +++ b/docs/api/sipcluster.md @@ -0,0 +1,461 @@ +

SIPCluster API reference

+

Packages:

+ +

airship.airshipit.org/v1

+

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

+Resource Types: + +

InfraConfig +

+

+(Appears on: +SIPClusterSpec) +

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+serviceType
+ + +InfraService + + +		 +
+optional
+ + +OptsConfig + + +		 +
+image
+ +string + +		 +
+nodelabels
+ +map[string]string + +		 +
+nodePort
+ +int + +		 +
+nodeInterfaceId
+ +string + +		 +
+
+
+

InfraService +(string alias)

+

+(Appears on: +InfraConfig) +

+

InfraService describes the type of infrastructure service that should be deployed when a sub-cluster is provisioned.

+

NodeSet +

+

+(Appears on: +SIPClusterSpec) +

+

NodeSet are the the list of Nodes objects workers, +or master that definee eexpectations +for the Tenant Clusters +Includes artifacts to associate with each defined namespace +Such as : +- Roles for the Nodes +- Flavor for theh Nodes image +- Scheduling expectations +- Scale of the group of Nodes

+
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+vm-flavor
+ +string + +		 +

VMFlavor is essentially a Flavor label identifying the +type of Node that meets the construction reqirements

+
+spreadTopology
+ + +SpreadTopology + + +		 +

PlaceHolder until we define the real expected +Implementation +Scheduling define constraints the allows the SIP Scheduler +to identify the required BMH’s to allow CAPI to build a cluster

+
+count
+ + +VMCount + + +		 +

Count defines the scale expectations for the Nodes

+
+
+
+

OptsConfig +

+

+(Appears on: +InfraConfig) +

+
+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+sshkey
+ +string + +		 +
+clusterIP
+ +string + +		 +
+
+
+

SIPCluster +

+

SIPCluster is the Schema for the sipclusters API

+
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+metadata
+ + +Kubernetes meta/v1.ObjectMeta + + +		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
+spec
+ + +SIPClusterSpec + + +		 +
+
+ + + + + + + + + + + + + +
+cluster-name
+ +string + +		 +

ClusterName is the name of the cluster to associate machines with

+
+nodes
+ + +map[./pkg/api/v1.VMRoles]./pkg/api/v1.NodeSet + + +		 +

Nodes are the list of Nodes objects workers, or master that definee eexpectations +of the Tenant cluster +VMRole is either Control or Workers +VMRole VMRoles json:"vm-role,omitempty"

+
+infra
+ + +[]InfraConfig + + +		 +

InfraServices is a list of services that are deployed when a SIPCluster is provisioned.

+
+
+status
+ + +SIPClusterStatus + + +		 +
+
+
+

SIPClusterSpec +

+

+(Appears on: +SIPCluster) +

+

SIPClusterSpec defines the desired state of a SIPCluster

+
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+cluster-name
+ +string + +		 +

ClusterName is the name of the cluster to associate machines with

+
+nodes
+ + +map[./pkg/api/v1.VMRoles]./pkg/api/v1.NodeSet + + +		 +

Nodes are the list of Nodes objects workers, or master that definee eexpectations +of the Tenant cluster +VMRole is either Control or Workers +VMRole VMRoles json:"vm-role,omitempty"

+
+infra
+ + +[]InfraConfig + + +		 +

InfraServices is a list of services that are deployed when a SIPCluster is provisioned.

+
+
+
+

SIPClusterStatus +

+

+(Appears on: +SIPCluster) +

+

SIPClusterStatus defines the observed state of SIPCluster

+
+
+ + + + + + + + + + + + + +
FieldDescription
+conditions
+ + +[]Kubernetes meta/v1.Condition + + +		 +
+
+
+

SpreadTopology +(string alias)

+

+(Appears on: +NodeSet) +

+

VMCount +

+

+(Appears on: +NodeSet) +

+

VMCount

+
+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+active
+ +int + +		 +

INSERT ADDITIONAL STATUS FIELD - define observed state of cluster +Important: Run “make” to regenerate code after modifying this file

+
+standby
+ +int + +		 +
+
+
+

VMRoles +(string alias)

+

VMRoles defines the states the provisioner will report +the tenant has having.

+
+

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..f6972a6 --- /dev/null +++ b/hack/api-docs/template/pkg.tpl @@ -0,0 +1,46 @@ +{{ define "packages" }} +

SIPCluster 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/tools/whitespace_linter b/tools/whitespace_linter index 280cef5..7b07925 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/sipcluster.md') if [[ -n "$trailing_whitespace" ]]; then printf "ERROR: Trailing whitespaces:\n"