Skip to content

Commit e182ef5

Browse files
zreigzzreigz
authored
docs: add CRD docs (#167)
* add CRD docs * change doc name
1 parent 14e2cf0 commit e182ef5

6 files changed

Lines changed: 242 additions & 45 deletions

File tree

‎Makefile‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ IMAGE_REPOSITORY := plural
88
IMG ?= deployment-agent:latest
99

1010
ENVTEST ?= $(shell which setup-envtest)
11+
CRDDOCS ?= $(shell which crd-ref-docs)
1112

1213
VELERO_CHART_VERSION := 5.2.2 # It should be kept in sync with Velero chart version from console/charts/velero
1314
VELERO_CHART_URL := https://github.com/vmware-tanzu/helm-charts/releases/download/velero-$(VELERO_CHART_VERSION)/velero-$(VELERO_CHART_VERSION).tgz
@@ -37,6 +38,10 @@ help: ## Display this help.
3738
controller-gen: ## Download controller-gen locally if necessary.
3839
$(call go-get-tool,$(CONTROLLER_GEN),sigs.k8s.io/controller-tools/cmd/controller-gen@v0.11.3)
3940

41+
.PHONY: crd-docs
42+
crd-docs: ##generate docs from the CRDs
43+
$(CRDDOCS) --source-path=./api --renderer=markdown --output-path=./docs/api.md --config=config.yaml
44+
4045
##@ Development
4146

4247
.PHONY: manifests
@@ -119,6 +124,10 @@ envtest: --tool ## Download and install setup-envtest in the $GOPATH/bin
119124
mockery: TOOL = mockery
120125
mockery: --tool
121126

127+
.PHONY: crd-ref-docs
128+
crd-ref-docs: TOOL = crd-ref-docs
129+
crd-ref-docs: --tool
130+
122131
# go-get-tool will 'go get' any package $2 and install it to $1.
123132
PROJECT_DIR := $(shell dirname $(abspath $(lastword $(MAKEFILE_LIST))))
124133
define go-get-tool

‎config.yaml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
processor:
2+
ignoreTypes:
3+
- ".*List$"
4+
ignoreFields:
5+
- "status$"
6+
- "TypeMeta$"
7+
8+
render:
9+
kubernetesVersion: 1.29
10+
knownTypes:
11+
- name: SecretObjectReference
12+
package: sigs.k8s.io/gateway-api/apis/v1beta1
13+
link: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.SecretObjectReference
14+
- name: ObjectReference
15+
package: k8s.io/api/core/v1
16+
link: https://pkg.go.dev/k8s.io/api/core/v1#ObjectReference
17+
- name: ObjectMeta
18+
package: k8s.io/apimachinery/pkg/apis/meta/v1
19+
link: https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#ObjectMeta
20+
- name: RawExtension
21+
package: k8s.io/apimachinery/pkg/runtime
22+
link: https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime#RawExtension

‎docs/api.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# API Reference
2+
3+
## Packages
4+
- [deployments.plural.sh/v1alpha1](#deploymentspluralshv1alpha1)
5+
6+
7+
## deployments.plural.sh/v1alpha1
8+
9+
Package v1alpha1 contains API Schema definitions for the deployments v1alpha1 API group
10+
11+
### Resource Types
12+
- [CustomHealth](#customhealth)
13+
- [PipelineGate](#pipelinegate)
14+
15+
16+
17+
18+
19+
20+
21+
22+
23+
#### CustomHealth
24+
25+
26+
27+
CustomHealth is the Schema for the HealthConverts API
28+
29+
30+
31+
32+
33+
| Field | Description | Default | Validation |
34+
| --- | --- | --- | --- |
35+
| `apiVersion` _string_ | `deployments.plural.sh/v1alpha1` | | |
36+
| `kind` _string_ | `CustomHealth` | | |
37+
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | |
38+
| `spec` _[CustomHealthSpec](#customhealthspec)_ | | | |
39+
40+
41+
#### CustomHealthSpec
42+
43+
44+
45+
CustomHealthSpec defines the desired state of CustomHealth
46+
47+
48+
49+
_Appears in:_
50+
- [CustomHealth](#customhealth)
51+
52+
| Field | Description | Default | Validation |
53+
| --- | --- | --- | --- |
54+
| `script` _string_ | | | |
55+
56+
57+
58+
59+
#### GateSpec
60+
61+
62+
63+
GateSpec defines the detailed gate specifications
64+
65+
66+
67+
_Appears in:_
68+
- [PipelineGateSpec](#pipelinegatespec)
69+
70+
| Field | Description | Default | Validation |
71+
| --- | --- | --- | --- |
72+
| `job` _[JobSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#jobspec-v1-batch)_ | resuse JobSpec type from the kubernetes api | | |
73+
74+
75+
#### GateState
76+
77+
_Underlying type:_ _GateState_
78+
79+
GateState represents the state of a gate, reused from console client
80+
81+
_Validation:_
82+
- Enum: [PENDING OPEN CLOSED RUNNING]
83+
84+
_Appears in:_
85+
- [PipelineGateStatus](#pipelinegatestatus)
86+
87+
88+
89+
#### GateType
90+
91+
_Underlying type:_ _GateType_
92+
93+
GateType represents the type of a gate, reused from console client
94+
95+
_Validation:_
96+
- Enum: [APPROVAL WINDOW JOB]
97+
98+
_Appears in:_
99+
- [PipelineGateSpec](#pipelinegatespec)
100+
101+
102+
103+
#### PipelineGate
104+
105+
106+
107+
PipelineGate represents a gate blocking promotion along a release pipeline
108+
109+
110+
111+
112+
113+
| Field | Description | Default | Validation |
114+
| --- | --- | --- | --- |
115+
| `apiVersion` _string_ | `deployments.plural.sh/v1alpha1` | | |
116+
| `kind` _string_ | `PipelineGate` | | |
117+
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | |
118+
| `spec` _[PipelineGateSpec](#pipelinegatespec)_ | | | |
119+
120+
121+
#### PipelineGateSpec
122+
123+
124+
125+
PipelineGateSpec defines the detailed gate specifications
126+
127+
128+
129+
_Appears in:_
130+
- [PipelineGate](#pipelinegate)
131+
132+
| Field | Description | Default | Validation |
133+
| --- | --- | --- | --- |
134+
| `id` _string_ | | | |
135+
| `name` _string_ | | | |
136+
| `type` _[GateType](#gatetype)_ | | | Enum: [APPROVAL WINDOW JOB] <br /> |
137+
| `gateSpec` _[GateSpec](#gatespec)_ | | | |
138+
139+
140+
141+

‎go.mod‎

Lines changed: 21 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ require (
66
github.com/Masterminds/semver/v3 v3.2.1
77
github.com/Masterminds/sprig/v3 v3.2.3
88
github.com/Yamashou/gqlgenc v0.18.1
9+
github.com/elastic/crd-ref-docs v0.0.12
910
github.com/evanphx/json-patch v5.7.0+incompatible
1011
github.com/fluxcd/flagger v1.35.0
1112
github.com/gin-gonic/gin v1.7.7
@@ -25,16 +26,16 @@ require (
2526
github.com/pluralsh/polly v0.1.7
2627
github.com/samber/lo v1.39.0
2728
github.com/spf13/pflag v1.0.5
28-
github.com/stretchr/testify v1.8.4
29+
github.com/stretchr/testify v1.9.0
2930
github.com/vektra/mockery/v2 v2.39.0
3031
github.com/vmware-tanzu/velero v1.13.0
3132
github.com/yuin/gopher-lua v1.1.1
32-
go.uber.org/zap v1.26.0
33-
golang.org/x/net v0.19.0
33+
go.uber.org/zap v1.27.0
34+
golang.org/x/net v0.22.0
3435
helm.sh/helm/v3 v3.14.3
3536
k8s.io/api v0.29.2
3637
k8s.io/apiextensions-apiserver v0.29.0
37-
k8s.io/apimachinery v0.29.2
38+
k8s.io/apimachinery v0.29.3
3839
k8s.io/cli-runtime v0.29.2
3940
k8s.io/client-go v0.29.2
4041
k8s.io/klog/v2 v2.110.1
@@ -60,6 +61,8 @@ require (
6061
github.com/BurntSushi/toml v1.3.2 // indirect
6162
github.com/MakeNowJust/heredoc v1.0.0 // indirect
6263
github.com/Masterminds/goutils v1.1.1 // indirect
64+
github.com/Masterminds/semver v1.5.0 // indirect
65+
github.com/Masterminds/sprig v2.22.0+incompatible // indirect
6366
github.com/Masterminds/squirrel v1.5.4 // indirect
6467
github.com/Microsoft/hcsshim v0.11.4 // indirect
6568
github.com/antlr/antlr4/runtime/Go/antlr/v4 v4.0.0-20230305170008-8188dc5388df // indirect
@@ -85,7 +88,7 @@ require (
8588
github.com/evanphx/json-patch/v5 v5.8.0 // indirect
8689
github.com/exponent-io/jsonpath v0.0.0-20151013193312-d6023ce2651d // indirect
8790
github.com/fatih/camelcase v1.0.0 // indirect
88-
github.com/fatih/color v1.15.0 // indirect
91+
github.com/fatih/color v1.16.0 // indirect
8992
github.com/felixge/httpsnoop v1.0.4 // indirect
9093
github.com/fsnotify/fsnotify v1.7.0 // indirect
9194
github.com/fvbommel/sortorder v1.1.0 // indirect
@@ -101,10 +104,12 @@ require (
101104
github.com/go-playground/universal-translator v0.17.0 // indirect
102105
github.com/go-playground/validator/v10 v10.4.1 // indirect
103106
github.com/go-task/slim-sprig v0.0.0-20230315185526-52ccab3ef572 // indirect
107+
github.com/gobuffalo/flect v1.0.2 // indirect
104108
github.com/gobwas/glob v0.2.3 // indirect
109+
github.com/goccy/go-yaml v1.11.3 // indirect
105110
github.com/gogo/protobuf v1.3.2 // indirect
106111
github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
107-
github.com/golang/protobuf v1.5.3 // indirect
112+
github.com/golang/protobuf v1.5.4 // indirect
108113
github.com/google/btree v1.0.1 // indirect
109114
github.com/google/cel-go v0.17.7 // indirect
110115
github.com/google/gnostic-models v0.6.8 // indirect
@@ -183,7 +188,7 @@ require (
183188
github.com/spf13/viper v1.15.0 // indirect
184189
github.com/spyzhov/ajson v0.9.0 // indirect
185190
github.com/stoewer/go-strcase v1.2.0 // indirect
186-
github.com/stretchr/objx v0.5.0 // indirect
191+
github.com/stretchr/objx v0.5.2 // indirect
187192
github.com/subosito/gotenv v1.4.2 // indirect
188193
github.com/ugorji/go/codec v1.1.7 // indirect
189194
github.com/vektah/gqlparser/v2 v2.5.11 // indirect
@@ -197,22 +202,23 @@ require (
197202
go.opentelemetry.io/otel/trace v1.21.0 // indirect
198203
go.starlark.net v0.0.0-20230525235612-a134d8f9ddca // indirect
199204
go.uber.org/multierr v1.11.0 // indirect
200-
golang.org/x/crypto v0.17.0 // indirect
205+
golang.org/x/crypto v0.21.0 // indirect
201206
golang.org/x/exp v0.0.0-20231006140011-7918f672742d // indirect
202-
golang.org/x/mod v0.14.0 // indirect
207+
golang.org/x/mod v0.16.0 // indirect
203208
golang.org/x/oauth2 v0.14.0 // indirect
204-
golang.org/x/sync v0.5.0 // indirect
205-
golang.org/x/sys v0.17.0 // indirect
206-
golang.org/x/term v0.17.0 // indirect
209+
golang.org/x/sync v0.6.0 // indirect
210+
golang.org/x/sys v0.18.0 // indirect
211+
golang.org/x/term v0.18.0 // indirect
207212
golang.org/x/text v0.14.0 // indirect
208213
golang.org/x/time v0.5.0 // indirect
209-
golang.org/x/tools v0.16.1 // indirect
214+
golang.org/x/tools v0.19.0 // indirect
215+
golang.org/x/xerrors v0.0.0-20231012003039-104605ab7028 // indirect
210216
gomodules.xyz/jsonpatch/v2 v2.4.0 // indirect
211217
google.golang.org/appengine v1.6.8 // indirect
212218
google.golang.org/genproto/googleapis/api v0.0.0-20231120223509-83a465c0220f // indirect
213219
google.golang.org/genproto/googleapis/rpc v0.0.0-20231120223509-83a465c0220f // indirect
214220
google.golang.org/grpc v1.60.1 // indirect
215-
google.golang.org/protobuf v1.31.0 // indirect
221+
google.golang.org/protobuf v1.33.0 // indirect
216222
gopkg.in/evanphx/json-patch.v5 v5.6.0 // indirect
217223
gopkg.in/inf.v0 v0.9.1 // indirect
218224
gopkg.in/ini.v1 v1.67.0 // indirect
@@ -223,6 +229,7 @@ require (
223229
k8s.io/kube-openapi v0.0.0-20231010175941-2dd684a91f00 // indirect
224230
k8s.io/utils v0.0.0-20230726121419-3b25d923346b // indirect
225231
oras.land/oras-go v1.2.4 // indirect
232+
sigs.k8s.io/controller-tools v0.14.0 // indirect
226233
sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd // indirect
227234
sigs.k8s.io/kustomize/api v0.16.0 // indirect
228235
sigs.k8s.io/structured-merge-diff/v4 v4.4.1 // indirect

0 commit comments

Comments
 (0)