Skip to content

Commit 1d29d91

Browse files
cezar-guimaraesbrunojdo
cezar-guimaraes
and
brunojdo
authored
Generate Markdown API reference (#6)
* add Makefile rule to generate api ref docs * Improve docs and generate Markdown version --------- Co-authored-by: Bruno Dias <[email protected]>
1 parent f586795 commit 1d29d91

File tree

5 files changed

+218
-24
lines changed

5 files changed

+218
-24
lines changed

‎Makefile‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,10 +105,20 @@ vet: ## Run go vet against code.
105105
test: manifests generate fmt vet envtest ## Run tests.
106106
KUBEBUILDER_ASSETS="$(shell $(ENVTEST) use $(ENVTEST_K8S_VERSION) --bin-dir $(LOCALBIN) -p path)" go test ./... -coverprofile cover.out
107107

108+
.PHONY: helm
108109
helm: manifests kustomize helmify ## Generate Helm chart.
109110
cd config/manager && $(KUSTOMIZE) edit set image controller=$(IMG)
110111
$(KUSTOMIZE) build config/default | $(HELMIFY) cleaner
111112

113+
.PHONY: coverage
114+
coverage: ## Opens HTML coverage report on browser.
115+
go tool cover -html=cover.out
116+
117+
.PHONY: gen-docs
118+
gen-docs: crd-ref-docs ## Generates Markdown API Reference.
119+
$(CRD_REF_DOCS) --source-path=./api/v1alpha1 --renderer=markdown
120+
mv out.md ./docs/api-reference.md
121+
112122
##@ Build
113123

114124
.PHONY: build
@@ -182,6 +192,7 @@ KUSTOMIZE ?= $(LOCALBIN)/kustomize
182192
CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen
183193
ENVTEST ?= $(LOCALBIN)/setup-envtest
184194
HELMIFY ?= $(LOCALBIN)/helmify
195+
CRD_REF_DOCS ?= $(LOCALBIN)/crd-ref-docs
185196

186197
## Tool Versions
187198
KUSTOMIZE_VERSION ?= v3.8.7
@@ -263,5 +274,12 @@ catalog-push: ## Push a catalog image.
263274
helmify: $(HELMIFY) ## Download helmify locally if necessary.
264275
$(HELMIFY): $(LOCALBIN)
265276
test -s $(LOCALBIN)/helmify || GOBIN=$(LOCALBIN) go install github.com/arttor/helmify/cmd/helmify@latest
266-
277+
278+
.PHONY: crd-ref-docs
279+
crd-ref-docs: $(CRD_REF_DOCS) ## Download crd-ref-docs locally if necessary.
280+
$(CRD_REF_DOCS): $(LOCALBIN)
281+
test -s $(LOCALBIN)/crd-ref-docs || \
282+
GOBIN=$(LOCALBIN) go install github.com/elastic/crd-ref-docs@3a11386f88f173eaf44c9542369ee060b038a58d
283+
# grabbing a specific commit because 0.0.9 which includes `useRawDocstring`
284+
# and correctly handles embedded fields hasn't been released
267285

‎api/v1alpha1/conditionalttl_types.go‎

Lines changed: 49 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,8 @@ import (
2121
"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
2222
)
2323

24-
// RetryConfig defines how the controller will retry the condition.
24+
// RetryConfig defines how the controller should retry evaluating the
25+
// set of conditions.
2526
type RetryConfig struct {
2627
// Period defines how long the controller should wait before retrying
2728
// the condition.
@@ -30,17 +31,22 @@ type RetryConfig struct {
3031
Period *metav1.Duration `json:"period"`
3132
}
3233

33-
// HelmConfig defines the helm release associated with the targetted resources
34-
// and whether the release should be deleted.
34+
// HelmConfig specifies a Helm release by its name and whether
35+
// the release should be deleted.
3536
type HelmConfig struct {
36-
// Release is the Helm release name.
37+
// The Helm Release name.
3738
Release string `json:"release,omitempty"`
3839

39-
// Delete specifies whether the Helm release should be deleted
40-
// whenever the ConditionalTTL is triggered.
40+
// Delete specifies whether the Helm release should be deleted.
4141
Delete bool `json:"delete,omitempty"`
4242
}
4343

44+
// TargetReference declares how a target group should be looked up.
45+
// A target group can reference either a single Kubernetes resource - in which case
46+
// finding it is required in other to evaluate the set of conditions - or
47+
// a collection of resources of the same GroupVersionKind. In contrast
48+
// with single targets, an empty collection is a valid value when evaluating
49+
// the set of conditions.
4450
type TargetReference struct {
4551
// TODO: apiVersion and kind of TypeMeta are optional, can they be made
4652
// required without duplicating it?
@@ -57,58 +63,74 @@ type TargetReference struct {
5763
LabelSelector *metav1.LabelSelector `json:"labelSelector"`
5864
}
5965

60-
// Target declares how to find one or more resources related to the ConditionalTTL.
61-
// Targets are watched in order to trigger a reevaluation of the conditions and, when
62-
// the ConditionalTTl is triggered they might be deleted by the controller.
66+
// Target declares how to find one or more resources related to the ConditionalTTL,
67+
// whether they should be deleted and whether they are necessary for evaluating the
68+
// set of conditions.
6369
type Target struct {
64-
// Name identifies this target group and identifies the target current
65-
// state when evaluating the CEL conditions.
70+
// Name identifies this target group and is used to refer to its state
71+
// when evaluating the set of conditions.
6672
// The name `time` is invalid and is included by default during evaluation.
6773
// +kubebuilder:validation:Pattern=`^[^t].*|t($|[^i]).*|ti($|[^m]).*|tim($|[^e]).*|time.+`
6874
Name string `json:"name"`
6975

70-
// Delete specifies whether this target group should be deleted
76+
// Delete indicates whether this target group should be deleted
7177
// when the ConditionalTTL is triggered.
7278
Delete bool `json:"delete"`
7379

74-
// IncludeWhenEvaluating specifies whether this target group should be
80+
// IncludeWhenEvaluating indicates whether this target group should be
7581
// included in the CEL evaluation context.
7682
IncludeWhenEvaluating bool `json:"includeWhenEvaluating"`
7783

78-
// Reference declares how to find either a single object, through its name,
79-
// or a collection, through LabelSelectors.
84+
// Reference declares how to find either a single object, using its name,
85+
// or a collection, using a LabelSelector.
8086
Reference TargetReference `json:"reference"`
8187
}
8288

83-
// ConditionalTTLSpec defines the desired state of ConditionalTTL
89+
// ConditionalTTLSpec represents the configuration for a ConditionalTTL object.
90+
// A ConditionalTTL's specification is the union of conditions under which
91+
// deletion begins and actions to be taken during it.
8492
type ConditionalTTLSpec struct {
85-
// TTL specifies the minimum duration the target objects will last
93+
// Duration the controller should wait relative to the ConditionalTTL's CreationTime
94+
// before starting deletion.
8695
// +kubebuilder:validation:Type=string
8796
// +kubebuilder:validation:Format=duration
8897
TTL *metav1.Duration `json:"ttl"`
8998

99+
// Specifies how the controller should retry the evaluation of conditions.
100+
// This field is required when the list of conditions is not empty.
90101
// +optional
91102
Retry *RetryConfig `json:"retry,omitempty"`
92103

104+
// Optional: Allows a ConditionalTTL to refer to and possibly delete a Helm release,
105+
// usually the release responsible for creating the targets of the ConditionalTTL.
93106
// +optional
94107
Helm *HelmConfig `json:"helm,omitempty"`
95108

109+
// List of targets the ConditionalTTL is interested in deleting or that are needed
110+
// for evaluating the conditions under which deletion should take place.
96111
Targets []Target `json:"targets,omitempty"`
97112

113+
// Optional list of [Common Expression Language](https://github.com/google/cel-spec) conditions
114+
// which should all evaluate to true before deletion takes place.
98115
// +optional
99116
Conditions []string `json:"conditions,omitempty"`
100117

101-
// TODO: validate https? protocol
118+
// Optional http(s) address the controller should send a [Cloud Event](https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md)
119+
// to after deletion takes place.
102120
// +optional
103121
CloudEventSink *string `json:"cloudEventSink,omitempty"`
104122
}
105123

106124
type TargetStatus struct {
107-
// Name matches the declared name on Spec.Targets.
125+
// Name is the target name as declared on `spec.targets`.
108126
Name string `json:"name"`
109127

128+
// Delete matches `.spec.targets.delete` for the target
129+
// identified by `name`.
110130
Delete bool `json:"delete"`
111131

132+
// IncludeWhenEvaluating matches `.spec.targets.includeWhenEvaluating` for the target
133+
// identified by `name`.
112134
IncludeWhenEvaluating bool `json:"includeWhenEvaluating"`
113135

114136
// State is the observed state of the target on the cluster
@@ -117,7 +139,7 @@ type TargetStatus struct {
117139
State *unstructured.Unstructured `json:"state,omitempty"`
118140
}
119141

120-
// ConditionalTTLStatus defines the observed state of ConditionalTTL
142+
// ConditionalTTLStatus defines the observed state of ConditionalTTL.
121143
type ConditionalTTLStatus struct {
122144
Targets []TargetStatus `json:"targets,omitempty"`
123145

@@ -134,7 +156,12 @@ type ConditionalTTLStatus struct {
134156
// +kubebuilder:printcolumn:name="Age",type="date",JSONPath=`.metadata.creationTimestamp`
135157
// +kubebuilder:printcolumn:name="TTL",type=string,format=date-time,JSONPath=`.spec.ttl`
136158
// +kubebuilder:printcolumn:name="Status",type=string,JSONPath=`.status.conditions[?(@.type=="Ready")].reason`
137-
// ConditionalTTL is the Schema for the conditionalttls API
159+
160+
// ConditionalTTL allows one to declare a set of conditions under which a set of
161+
// resources should be deleted.
162+
//
163+
// The ConditionalTTL's controller will track the statuses of its referenced Targets,
164+
// periodically re-evaluating the declared conditions for deletion.
138165
type ConditionalTTL struct {
139166
metav1.TypeMeta `json:",inline"`
140167
metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -145,7 +172,7 @@ type ConditionalTTL struct {
145172

146173
//+kubebuilder:object:root=true
147174

148-
// ConditionalTTLList contains a list of ConditionalTTL
175+
// ConditionalTTLList contains a list of ConditionalTTL.
149176
type ConditionalTTLList struct {
150177
metav1.TypeMeta `json:",inline"`
151178
metav1.ListMeta `json:"metadata,omitempty"`

‎api/v1alpha1/groupversion_info.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
1414
limitations under the License.
1515
*/
1616

17-
// Package v1alpha1 contains API Schema definitions for the cleaner v1alpha1 API group
17+
// Package v1alpha1 contains API Schema definitions for the cleaner v1alpha1 API group.
1818
// +kubebuilder:object:generate=true
1919
// +groupName=cleaner.vtex.io
2020
package v1alpha1

‎config.yaml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Options used by the api docs generator
2+
# https://github.com/elastic/crd-ref-docs
3+
#
4+
# To regenerate the docs, use `make gen-docs`
5+
6+
processor:
7+
# RE2 regular expressions describing types that should be excluded from the generated documentation.
8+
ignoreTypes:
9+
- "ConditionalTTLList$"
10+
- "TargetStatus$"
11+
# RE2 regular expressions describing type fields that should be excluded from the generated documentation.
12+
ignoreFields:
13+
- "status$"
14+
- "ConditionalTTL.TypeMeta$"
15+
useRawDocstring: true
16+
17+
render:
18+
# Version of Kubernetes to use when generating links to Kubernetes API documentation.
19+
kubernetesVersion: 1.24

‎docs/api-reference.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# API Reference
2+
3+
## Packages
4+
- [cleaner.vtex.io/v1alpha1](#cleanervtexiov1alpha1)
5+
6+
7+
## cleaner.vtex.io/v1alpha1
8+
9+
Package v1alpha1 contains API Schema definitions for the cleaner v1alpha1 API group.
10+
11+
### Resource Types
12+
- [ConditionalTTL](#conditionalttl)
13+
14+
15+
16+
#### ConditionalTTL
17+
18+
19+
20+
ConditionalTTL allows one to declare a set of conditions under which a set of
21+
resources should be deleted.
22+
23+
The ConditionalTTL's controller will track the statuses of its referenced Targets,
24+
periodically re-evaluating the declared conditions for deletion.
25+
26+
27+
28+
| Field | Description |
29+
| --- | --- |
30+
| `apiVersion` _string_ | `cleaner.vtex.io/v1alpha1`
31+
| `kind` _string_ | `ConditionalTTL`
32+
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |
33+
| `spec` _[ConditionalTTLSpec](#conditionalttlspec)_ | |
34+
35+
36+
#### ConditionalTTLSpec
37+
38+
39+
40+
ConditionalTTLSpec represents the configuration for a ConditionalTTL object.
41+
A ConditionalTTL's specification is the union of conditions under which
42+
deletion begins and actions to be taken during it.
43+
44+
_Appears in:_
45+
- [ConditionalTTL](#conditionalttl)
46+
47+
| Field | Description |
48+
| --- | --- |
49+
| `ttl` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#duration-v1-meta)_ | Duration the controller should wait relative to the ConditionalTTL's CreationTime before starting deletion. |
50+
| `retry` _[RetryConfig](#retryconfig)_ | Specifies how the controller should retry the evaluation of conditions. This field is required when the list of conditions is not empty. |
51+
| `helm` _[HelmConfig](#helmconfig)_ | Optional: Allows a ConditionalTTL to refer to and possibly delete a Helm release, usually the release responsible for creating the targets of the ConditionalTTL. |
52+
| `targets` _[Target](#target) array_ | List of targets the ConditionalTTL is interested in deleting or that are needed for evaluating the conditions under which deletion should take place. |
53+
| `conditions` _string array_ | Optional list of [Common Expression Language](https://github.com/google/cel-spec) conditions which should all evaluate to true before deletion takes place. |
54+
| `cloudEventSink` _string_ | Optional http(s) address the controller should send a [Cloud Event](https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md) to after deletion takes place. |
55+
56+
57+
58+
59+
#### HelmConfig
60+
61+
62+
63+
HelmConfig specifies a Helm release by its name and whether
64+
the release should be deleted.
65+
66+
_Appears in:_
67+
- [ConditionalTTLSpec](#conditionalttlspec)
68+
69+
| Field | Description |
70+
| --- | --- |
71+
| `release` _string_ | The Helm Release name. |
72+
| `delete` _boolean_ | Delete specifies whether the Helm release should be deleted. |
73+
74+
75+
#### RetryConfig
76+
77+
78+
79+
RetryConfig defines how the controller should retry evaluating the
80+
set of conditions.
81+
82+
_Appears in:_
83+
- [ConditionalTTLSpec](#conditionalttlspec)
84+
85+
| Field | Description |
86+
| --- | --- |
87+
| `period` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#duration-v1-meta)_ | Period defines how long the controller should wait before retrying the condition. |
88+
89+
90+
#### Target
91+
92+
93+
94+
Target declares how to find one or more resources related to the ConditionalTTL,
95+
whether they should be deleted and whether they are necessary for evaluating the
96+
set of conditions.
97+
98+
_Appears in:_
99+
- [ConditionalTTLSpec](#conditionalttlspec)
100+
101+
| Field | Description |
102+
| --- | --- |
103+
| `name` _string_ | Name identifies this target group and is used to refer to its state when evaluating the set of conditions. The name `time` is invalid and is included by default during evaluation. |
104+
| `delete` _boolean_ | Delete indicates whether this target group should be deleted when the ConditionalTTL is triggered. |
105+
| `includeWhenEvaluating` _boolean_ | IncludeWhenEvaluating indicates whether this target group should be included in the CEL evaluation context. |
106+
| `reference` _[TargetReference](#targetreference)_ | Reference declares how to find either a single object, using its name, or a collection, using a LabelSelector. |
107+
108+
109+
#### TargetReference
110+
111+
112+
113+
TargetReference declares how a target group should be looked up.
114+
A target group can reference either a single Kubernetes resource - in which case
115+
finding it is required in other to evaluate the set of conditions - or
116+
a collection of resources of the same GroupVersionKind. In contrast
117+
with single targets, an empty collection is a valid value when evaluating
118+
the set of conditions.
119+
120+
_Appears in:_
121+
- [Target](#target)
122+
123+
| Field | Description |
124+
| --- | --- |
125+
| `kind` _string_ | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds |
126+
| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources |
127+
| `name` _string_ | Name matches a single object. If name is specified, LabelSelector is ignored. |
128+
| `labelSelector` _[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#labelselector-v1-meta)_ | LabelSelector allows more than one object to be included in the target group. If Name is not empty, LabelSelector is ignored. |
129+
130+

0 commit comments

Comments
 (0)