Skip to content

Commit 57ceb40

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #2610 from everettraven/feature/GH2597-readme-template
✨ (go/v3): Add README.md template to scaffolding templates
2 parents 7cfa7ff + c94dabc commit 57ceb40

File tree

7 files changed

+600
-0
lines changed

7 files changed

+600
-0
lines changed

‎pkg/plugins/golang/v3/scaffolds/init.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,5 +112,6 @@ func (s *initScaffolder) Scaffold() error {
112112
},
113113
&templates.Dockerfile{},
114114
&templates.DockerIgnore{},
115+
&templates.Readme{},
115116
)
116117
}

‎pkg/plugins/golang/v3/scaffolds/internal/templates/readme.go‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
/*
2+
Copyright 2022 The Kubernetes Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package templates
18+
19+
import (
20+
"fmt"
21+
"strings"
22+
23+
"sigs.k8s.io/kubebuilder/v3/pkg/machinery"
24+
)
25+
26+
var _ machinery.Template = &Readme{}
27+
28+
// Readme scaffolds a README.md file
29+
type Readme struct {
30+
machinery.TemplateMixin
31+
machinery.BoilerplateMixin
32+
machinery.ProjectNameMixin
33+
34+
License string
35+
}
36+
37+
// SetTemplateDefaults implements file.Template
38+
func (f *Readme) SetTemplateDefaults() error {
39+
if f.Path == "" {
40+
f.Path = "README.md"
41+
}
42+
43+
f.License = strings.Replace(
44+
strings.Replace(string(f.Boilerplate), "/*", "", 1),
45+
"*/", "", 1)
46+
47+
f.TemplateBody = fmt.Sprintf(readmeFileTemplate,
48+
codeFence("sh", "kubectl apply -f config/samples/"),
49+
codeFence("sh", "make docker-build docker-push IMG=<some-registry>/{{ .ProjectName }}:tag"),
50+
codeFence("sh", "make deploy IMG=<some-registry>/{{ .ProjectName }}:tag"),
51+
codeFence("sh", "make uninstall"),
52+
codeFence("sh", "make undeploy"),
53+
codeFence("sh", "make install"),
54+
codeFence("sh", "make run"),
55+
codeFence("sh", "make manifests"))
56+
57+
return nil
58+
}
59+
60+
//nolint:lll
61+
const readmeFileTemplate = `# {{ .ProjectName }}
62+
// TODO(user): Add simple overview of use/purpose
63+
64+
## Description
65+
// TODO(user): An in-depth paragraph about your project and overview of use
66+
67+
## Getting Started
68+
You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster.
69+
**Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster ` + "`kubectl cluster-info`" + ` shows).
70+
71+
### Running on the cluster
72+
1. Install Instances of Custom Resources:
73+
74+
%s
75+
76+
2. Build and push your image to the location specified by ` + "`IMG`" + `:
77+
78+
%s
79+
80+
3. Deploy the controller to the cluster with the image specified by ` + "`IMG`" + `:
81+
82+
%s
83+
84+
### Uninstall CRDs
85+
To delete the CRDs from the cluster:
86+
87+
%s
88+
89+
### Undeploy controller
90+
UnDeploy the controller to the cluster:
91+
92+
%s
93+
94+
## Contributing
95+
// TODO(user): Add detailed information on how you would like others to contribute to this project
96+
97+
### How it works
98+
This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)
99+
100+
It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/)
101+
which provides a reconcile function responsible for synchronizing resources untile the desired state is reached on the cluster
102+
103+
### Test It Out
104+
1. Install the CRDs into the cluster:
105+
106+
%s
107+
108+
2. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running):
109+
110+
%s
111+
112+
**NOTE:** You can also run this in one step by running: ` + "`make install run`" + `
113+
114+
### Modifying the API definitions
115+
If you are editing the API definitions, generate the manifests such as CRs or CRDs using:
116+
117+
%s
118+
119+
**NOTE:** Run ` + "`make --help`" + ` for more information on all potential ` + "`make`" + ` targets
120+
121+
More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
122+
123+
## License
124+
{{ .License }}
125+
`
126+
127+
func codeFence(syntax string, code string) string {
128+
return "```" + syntax + "\n" + code + "\n" + "```"
129+
}

‎testdata/project-v3-addon/README.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# project-v3-addon
2+
// TODO(user): Add simple overview of use/purpose
3+
4+
## Description
5+
// TODO(user): An in-depth paragraph about your project and overview of use
6+
7+
## Getting Started
8+
You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster.
9+
**Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows).
10+
11+
### Running on the cluster
12+
1. Install Instances of Custom Resources:
13+
14+
```sh
15+
kubectl apply -f config/samples/
16+
```
17+
18+
2. Build and push your image to the location specified by `IMG`:
19+
20+
```sh
21+
make docker-build docker-push IMG=<some-registry>/project-v3-addon:tag
22+
```
23+
24+
3. Deploy the controller to the cluster with the image specified by `IMG`:
25+
26+
```sh
27+
make deploy IMG=<some-registry>/project-v3-addon:tag
28+
```
29+
30+
### Uninstall CRDs
31+
To delete the CRDs from the cluster:
32+
33+
```sh
34+
make uninstall
35+
```
36+
37+
### Undeploy controller
38+
UnDeploy the controller to the cluster:
39+
40+
```sh
41+
make undeploy
42+
```
43+
44+
## Contributing
45+
// TODO(user): Add detailed information on how you would like others to contribute to this project
46+
47+
### How it works
48+
This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)
49+
50+
It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/)
51+
which provides a reconcile function responsible for synchronizing resources untile the desired state is reached on the cluster
52+
53+
### Test It Out
54+
1. Install the CRDs into the cluster:
55+
56+
```sh
57+
make install
58+
```
59+
60+
2. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running):
61+
62+
```sh
63+
make run
64+
```
65+
66+
**NOTE:** You can also run this in one step by running: `make install run`
67+
68+
### Modifying the API definitions
69+
If you are editing the API definitions, generate the manifests such as CRs or CRDs using:
70+
71+
```sh
72+
make manifests
73+
```
74+
75+
**NOTE:** Run `make --help` for more information on all potential `make` targets
76+
77+
More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
78+
79+
## License
80+
81+
Copyright 2022 The Kubernetes authors.
82+
83+
Licensed under the Apache License, Version 2.0 (the "License");
84+
you may not use this file except in compliance with the License.
85+
You may obtain a copy of the License at
86+
87+
http://www.apache.org/licenses/LICENSE-2.0
88+
89+
Unless required by applicable law or agreed to in writing, software
90+
distributed under the License is distributed on an "AS IS" BASIS,
91+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
92+
See the License for the specific language governing permissions and
93+
limitations under the License.
94+

‎testdata/project-v3-config/README.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# project-v3-config
2+
// TODO(user): Add simple overview of use/purpose
3+
4+
## Description
5+
// TODO(user): An in-depth paragraph about your project and overview of use
6+
7+
## Getting Started
8+
You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster.
9+
**Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows).
10+
11+
### Running on the cluster
12+
1. Install Instances of Custom Resources:
13+
14+
```sh
15+
kubectl apply -f config/samples/
16+
```
17+
18+
2. Build and push your image to the location specified by `IMG`:
19+
20+
```sh
21+
make docker-build docker-push IMG=<some-registry>/project-v3-config:tag
22+
```
23+
24+
3. Deploy the controller to the cluster with the image specified by `IMG`:
25+
26+
```sh
27+
make deploy IMG=<some-registry>/project-v3-config:tag
28+
```
29+
30+
### Uninstall CRDs
31+
To delete the CRDs from the cluster:
32+
33+
```sh
34+
make uninstall
35+
```
36+
37+
### Undeploy controller
38+
UnDeploy the controller to the cluster:
39+
40+
```sh
41+
make undeploy
42+
```
43+
44+
## Contributing
45+
// TODO(user): Add detailed information on how you would like others to contribute to this project
46+
47+
### How it works
48+
This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)
49+
50+
It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/)
51+
which provides a reconcile function responsible for synchronizing resources untile the desired state is reached on the cluster
52+
53+
### Test It Out
54+
1. Install the CRDs into the cluster:
55+
56+
```sh
57+
make install
58+
```
59+
60+
2. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running):
61+
62+
```sh
63+
make run
64+
```
65+
66+
**NOTE:** You can also run this in one step by running: `make install run`
67+
68+
### Modifying the API definitions
69+
If you are editing the API definitions, generate the manifests such as CRs or CRDs using:
70+
71+
```sh
72+
make manifests
73+
```
74+
75+
**NOTE:** Run `make --help` for more information on all potential `make` targets
76+
77+
More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
78+
79+
## License
80+
81+
Copyright 2022 The Kubernetes authors.
82+
83+
Licensed under the Apache License, Version 2.0 (the "License");
84+
you may not use this file except in compliance with the License.
85+
You may obtain a copy of the License at
86+
87+
http://www.apache.org/licenses/LICENSE-2.0
88+
89+
Unless required by applicable law or agreed to in writing, software
90+
distributed under the License is distributed on an "AS IS" BASIS,
91+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
92+
See the License for the specific language governing permissions and
93+
limitations under the License.
94+

0 commit comments

Comments
 (0)