Generate API documentation

Makefile

@@ -1,4 +1,3 @@
-
 # Image URL to use all building/pushing image targets
 IMG ?= fluxcd/source-controller:latest
 # Produce CRDs that work back to Kubernetes 1.13
@@ -14,7 +13,7 @@ endif
 all: manager
 
 # Run tests
-test: generate fmt vet manifests
+test: generate fmt vet manifests api-docs
 	go test ./... -coverprofile cover.out
 
 # Build manager binary
@@ -49,6 +48,10 @@ dev-deploy: manifests
 manifests: controller-gen
 	$(CONTROLLER_GEN) $(CRD_OPTIONS) rbac:roleName=manager-role paths="./..." output:crd:artifacts:config=config/crd/bases
 
+# Generate API reference documentation
+api-docs: gen-crd-api-reference-docs
+	$(API_REF_GEN) -api-dir=./api/v1alpha1 -config=./hack/api-docs/config.json -template-dir=./hack/api-docs/template -out-file=./docs/api/source.md
+
 # Run go fmt against code
 fmt:
 	go fmt ./...
@@ -84,3 +87,19 @@ CONTROLLER_GEN=$(GOBIN)/controller-gen
 else
 CONTROLLER_GEN=$(shell which controller-gen)
 endif
+
+# 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

api/v1alpha1/doc.go

@@ -0,0 +1,20 @@
+/*
+Copyright 2020 The Flux CD contributors.
+
+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 v1alpha1 contains API Schema definitions for the source v1alpha1 API group
+// +kubebuilder:object:generate=true
+// +groupName=source.fluxcd.io
+package v1alpha1

api/v1alpha1/gitrepository_types.go

@@ -199,6 +199,8 @@ func (in *GitRepository) GetInterval() metav1.Duration {
 	return in.Spec.Interval
 }
 
+// +genclient
+// +genclient:Namespaced
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
 // +kubebuilder:printcolumn:name="URL",type=string,JSONPath=`.spec.url`

api/v1alpha1/groupversion_info.go

@@ -14,9 +14,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// Package v1alpha1 contains API Schema definitions for the source v1alpha1 API group
-// +kubebuilder:object:generate=true
-// +groupName=source.fluxcd.io
 package v1alpha1
 
 import (

api/v1alpha1/helmchart_types.go

@@ -147,6 +147,8 @@ func (in *HelmChart) GetInterval() metav1.Duration {
 	return in.Spec.Interval
 }
 
+// +genclient
+// +genclient:Namespaced
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
 // +kubebuilder:printcolumn:name="Name",type=string,JSONPath=`.spec.name`

api/v1alpha1/helmrepository_types.go

@@ -146,6 +146,8 @@ func (in *HelmRepository) GetInterval() metav1.Duration {
 	return in.Spec.Interval
 }
 
+// +genclient
+// +genclient:Namespaced
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
 // +kubebuilder:printcolumn:name="URL",type=string,JSONPath=`.spec.url`