Skip to content

Commit bb21191

Browse files
demirkayaenderdemirkayaender
committed
Add more documentation + refactor
Signed-off-by: Ender Demirkaya <[email protected]>
1 parent b9abeed commit bb21191

File tree

5 files changed

+129
-86
lines changed

5 files changed

+129
-86
lines changed

‎new_samples/hello_world/generator/README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<!-- THIS IS A GENERATED FILE -->
2+
<!-- PLEASE DO NOT EDIT -->
3+
4+
# Sample Generator
5+
6+
This folder is NOT part of the actual sample. It exists only for contributors who work on this sample. Please disregard it if you are trying to learn about Cadence.
7+
8+
To create a better learning experience for Cadence users, each sample folder is designed to be self contained. Users can view every part of writing and running workflows, including:
9+
10+
* Cadence client initialization
11+
* Worker with workflow and activity registrations
12+
* Workflow starter
13+
* and the workflow code itself
14+
15+
Some samples may have more or fewer parts depending on what they need to demonstrate.
16+
17+
In most cases, the workflow code (e.g. `workflow.go`) is the part that users care about. The rest is boilerplate needed to run that workflow. For each sample folder, the workflow code should be written by hand. The boilerplate can be generated. Keeping all parts inside one folder gives early learners more value because they can see everything together rather than jumping across directories.
18+
19+
## Contributing
20+
21+
* When creating a new sample, follow the steps mentioned in the README file in the main samples folder.
22+
* To update the sample workflow code, edit the workflow file directly.
23+
* To update the worker, client, or other boilerplate logic, edit the generator file. If your change applies to all samples, update the common generator file inside the `template` folder. Edit the generator file in this folder only when the change should affect this sample alone.

‎new_samples/hello_world/generator/generate.go‎

Lines changed: 4 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1,98 +1,16 @@
11
package main
22

3-
import (
4-
"io"
5-
"os"
6-
"text/template"
7-
)
8-
9-
type TemplateData struct {
10-
SampleName string
11-
Workflows []string
12-
Activities []string
13-
}
3+
import "github.com/uber-common/cadence-samples/new_samples/template"
144

155
func main() {
166
// Define the data for HelloWorld
17-
data := TemplateData{
7+
data := template.TemplateData{
188
SampleName: "Hello World",
199
Workflows: []string{"HelloWorldWorkflow"},
2010
Activities: []string{"HelloWorldActivity"},
2111
}
2212

23-
// Generate worker.go
24-
generateFile("../../template/worker.tmpl", "../worker.go", data)
25-
println("Generated worker.go")
26-
27-
// Generate main.go
28-
generateFile("../../template/main.tmpl", "../main.go", data)
29-
println("Generated main.go")
30-
31-
// Generate README.md (combine template + specific + references)
32-
generateREADME("../../template/README.tmpl", "README_specific.md", "../../template/README_references.md", "../README.md", data)
33-
println("Generated README.md")
34-
}
35-
36-
func generateFile(templatePath, outputPath string, data TemplateData) {
37-
tmpl, err := template.ParseFiles(templatePath)
38-
if err != nil {
39-
panic("Failed to parse template " + templatePath + ": " + err.Error())
40-
}
41-
42-
f, err := os.Create(outputPath)
43-
if err != nil {
44-
panic("Failed to create output file " + outputPath + ": " + err.Error())
45-
}
46-
defer f.Close()
47-
48-
err = tmpl.Execute(f, data)
49-
if err != nil {
50-
panic("Failed to execute template: " + err.Error())
51-
}
13+
template.GenerateAll(data)
5214
}
5315

54-
func generateREADME(templatePath, specificPath, referencesPath, outputPath string, data TemplateData) {
55-
// Create output file
56-
f, err := os.Create(outputPath)
57-
if err != nil {
58-
panic("Failed to create README file: " + err.Error())
59-
}
60-
defer f.Close()
61-
62-
// First, write the generic template part
63-
tmpl, err := template.ParseFiles(templatePath)
64-
if err != nil {
65-
panic("Failed to parse README template: " + err.Error())
66-
}
67-
68-
err = tmpl.Execute(f, data)
69-
if err != nil {
70-
panic("Failed to execute README template: " + err.Error())
71-
}
72-
73-
// Then, append the specific content
74-
specific, err := os.Open(specificPath)
75-
if err != nil {
76-
panic("Failed to open specific README content: " + err.Error())
77-
}
78-
defer specific.Close()
79-
80-
_, err = io.Copy(f, specific)
81-
if err != nil {
82-
panic("Failed to append specific README content: " + err.Error())
83-
}
84-
85-
// Finally, append the references
86-
references, err := os.Open(referencesPath)
87-
if err != nil {
88-
panic("Failed to open references content: " + err.Error())
89-
}
90-
defer references.Close()
91-
92-
_, err = io.Copy(f, references)
93-
if err != nil {
94-
panic("Failed to append references content: " + err.Error())
95-
}
96-
}
97-
98-
16+
// Implement custom generator below

‎new_samples/template/README_generator.tmpl‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<!-- THIS IS A GENERATED FILE -->
2+
<!-- PLEASE DO NOT EDIT -->
3+
4+
# Sample Generator
5+
6+
This folder is NOT part of the actual sample. It exists only for contributors who work on this sample. Please disregard it if you are trying to learn about Cadence.
7+
8+
To create a better learning experience for Cadence users, each sample folder is designed to be self contained. Users can view every part of writing and running workflows, including:
9+
10+
* Cadence client initialization
11+
* Worker with workflow and activity registrations
12+
* Workflow starter
13+
* and the workflow code itself
14+
15+
Some samples may have more or fewer parts depending on what they need to demonstrate.
16+
17+
In most cases, the workflow code (e.g. `workflow.go`) is the part that users care about. The rest is boilerplate needed to run that workflow. For each sample folder, the workflow code should be written by hand. The boilerplate can be generated. Keeping all parts inside one folder gives early learners more value because they can see everything together rather than jumping across directories.
18+
19+
## Contributing
20+
21+
* When creating a new sample, follow the steps mentioned in the README file in the main samples folder.
22+
* To update the sample workflow code, edit the workflow file directly.
23+
* To update the worker, client, or other boilerplate logic, edit the generator file. If your change applies to all samples, update the common generator file inside the `template` folder. Edit the generator file in this folder only when the change should affect this sample alone.

‎new_samples/template/README_references.md‎ renamed to ‎new_samples/template/README_references.tmpl‎

File renamed without changes.

‎new_samples/template/generator.go‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
package template
2+
3+
import (
4+
"os"
5+
"text/template"
6+
)
7+
8+
type TemplateData struct {
9+
SampleName string
10+
Workflows []string
11+
Activities []string
12+
}
13+
14+
func GenerateAll(data TemplateData) {
15+
GenerateWorker(data)
16+
GenerateMain(data)
17+
GenerateSampleReadMe(data)
18+
GenerateGeneratorReadMe(data)
19+
}
20+
21+
func GenerateWorker(data TemplateData) {
22+
GenerateFile("../../template/worker.tmpl", "../worker.go", data)
23+
println("Generated worker.go")
24+
}
25+
26+
func GenerateMain(data TemplateData) {
27+
GenerateFile("../../template/main.tmpl", "../main.go", data)
28+
println("Generated main.go")
29+
}
30+
31+
func GenerateSampleReadMe(data TemplateData) {
32+
inputs := []string{"../../template/README.tmpl", "README_specific.md", "../../template/README_references.tmpl"}
33+
GenerateREADME(inputs, "../README.md", data)
34+
}
35+
36+
func GenerateGeneratorReadMe(data TemplateData) {
37+
GenerateFile("../../template/README_generator.tmpl", "README.md", data)
38+
println("Generated README.md")
39+
}
40+
41+
func GenerateFile(templatePath, outputPath string, data TemplateData) {
42+
tmpl, err := template.ParseFiles(templatePath)
43+
if err != nil {
44+
panic("Failed to parse template " + templatePath + ": " + err.Error())
45+
}
46+
47+
f, err := os.Create(outputPath)
48+
if err != nil {
49+
panic("Failed to create output file " + outputPath + ": " + err.Error())
50+
}
51+
defer f.Close()
52+
53+
err = tmpl.Execute(f, data)
54+
if err != nil {
55+
panic("Failed to execute template: " + err.Error())
56+
}
57+
}
58+
59+
func GenerateREADME(inputs []string, outputPath string, data TemplateData) {
60+
// Create output file
61+
f, err := os.Create(outputPath)
62+
if err != nil {
63+
panic("Failed to create README file: " + err.Error())
64+
}
65+
defer f.Close()
66+
67+
for _, input := range inputs {
68+
tmpl, err := template.ParseFiles(input)
69+
if err != nil {
70+
panic("Failed to parse README template: " + err.Error())
71+
}
72+
73+
err = tmpl.Execute(f, data)
74+
if err != nil {
75+
panic(input + ": Failed to append README content: " + err.Error())
76+
}
77+
}
78+
79+
}

0 commit comments

Comments
 (0)