Generate API documentation
This commit is contained in:
Hidde Beydals
parent
eb5ed4f86a
commit
7e647a6bb2
23
Makefile
23
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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 (
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,24 @@
|
|||
{
|
||||
"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/(api|apimachinery/pkg/apis)/",
|
||||
"docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}"
|
||||
}
|
||||
],
|
||||
"typeDisplayNamePrefixOverrides": {
|
||||
"k8s.io/api/": "Kubernetes ",
|
||||
"k8s.io/apimachinery/pkg/apis/": "Kubernetes "
|
||||
},
|
||||
"markdownDisabled": false
|
||||
}
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
{{ define "members" }}
|
||||
{{ range .Members }}
|
||||
{{ if not (hiddenMember .)}}
|
||||
<tr>
|
||||
<td>
|
||||
<code>{{ fieldName . }}</code><br>
|
||||
<em>
|
||||
{{ if linkForType .Type }}
|
||||
<a href="{{ linkForType .Type }}">
|
||||
{{ typeDisplayName .Type }}
|
||||
</a>
|
||||
{{ else }}
|
||||
{{ typeDisplayName .Type }}
|
||||
{{ end }}
|
||||
</em>
|
||||
</td>
|
||||
<td>
|
||||
{{ if fieldEmbedded . }}
|
||||
<p>
|
||||
(Members of <code>{{ fieldName . }}</code> are embedded into this type.)
|
||||
</p>
|
||||
{{ end}}
|
||||
|
||||
{{ if isOptionalMember .}}
|
||||
<em>(Optional)</em>
|
||||
{{ end }}
|
||||
|
||||
{{ safe (renderComments .CommentLines) }}
|
||||
|
||||
{{ if and (eq (.Type.Name.Name) "ObjectMeta") }}
|
||||
Refer to the Kubernetes API documentation for the fields of the
|
||||
<code>metadata</code> field.
|
||||
{{ end }}
|
||||
|
||||
{{ if or (eq (fieldName .) "spec") }}
|
||||
<br/>
|
||||
<br/>
|
||||
<table>
|
||||
{{ template "members" .Type }}
|
||||
</table>
|
||||
{{ end }}
|
||||
</td>
|
||||
</tr>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
{{ define "packages" }}
|
||||
<h1>Source API reference</h1>
|
||||
|
||||
{{ with .packages}}
|
||||
<p>Packages:</p>
|
||||
<ul class="simple">
|
||||
{{ range . }}
|
||||
<li>
|
||||
<a href="#{{- packageAnchorID . -}}">{{ packageDisplayName . }}</a>
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end}}
|
||||
|
||||
{{ range .packages }}
|
||||
<h2 id="{{- packageAnchorID . -}}">
|
||||
{{- packageDisplayName . -}}
|
||||
</h2>
|
||||
|
||||
{{ with (index .GoPackages 0 )}}
|
||||
{{ with .DocComments }}
|
||||
{{ safe (renderComments .) }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
||||
Resource Types:
|
||||
|
||||
<ul class="simple">
|
||||
{{- range (visibleTypes (sortedTypes .Types)) -}}
|
||||
{{ if isExportedType . -}}
|
||||
<li>
|
||||
<a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
|
||||
</li>
|
||||
{{- end }}
|
||||
{{- end -}}
|
||||
</ul>
|
||||
|
||||
{{ range (visibleTypes (sortedTypes .Types))}}
|
||||
{{ template "type" . }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
||||
<div class="admonition note">
|
||||
<p class="last">This page was automatically generated with <code>gen-crd-api-reference-docs</code></p>
|
||||
</div>
|
||||
{{ end }}
|
||||
|
|
@ -0,0 +1,60 @@
|
|||
{{ define "type" }}
|
||||
<h3 id="{{ anchorIDForType . }}">
|
||||
{{- .Name.Name }}
|
||||
{{ if eq .Kind "Alias" }}(<code>{{.Underlying}}</code> alias){{ end -}}
|
||||
</h3>
|
||||
|
||||
{{ with (typeReferences .) }}
|
||||
<p>
|
||||
(<em>Appears on:</em>
|
||||
{{- $prev := "" -}}
|
||||
{{- range . -}}
|
||||
{{- if $prev -}}, {{ end -}}
|
||||
{{ $prev = . }}
|
||||
<a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
|
||||
{{- end -}}
|
||||
)
|
||||
</p>
|
||||
{{ end }}
|
||||
|
||||
{{ with .CommentLines }}
|
||||
{{ safe (renderComments .) }}
|
||||
{{ end }}
|
||||
|
||||
{{ if .Members }}
|
||||
<div class="md-typeset__scrollwrap">
|
||||
<div class="md-typeset__table">
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Field</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{{ if isExportedType . }}
|
||||
<tr>
|
||||
<td>
|
||||
<code>apiVersion</code><br>
|
||||
string</td>
|
||||
<td>
|
||||
<code>{{ apiGroup . }}</code>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<code>kind</code><br>
|
||||
string
|
||||
</td>
|
||||
<td>
|
||||
<code>{{ .Name.Name }}</code>
|
||||
</td>
|
||||
</tr>
|
||||
{{ end }}
|
||||
{{ template "members" . }}
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</div>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
Loading…
Reference in New Issue