Merge pull request #655 from jamiehannaford/doc-delimiter

Add custom content blocks to generator

generator/README.md

@@ -16,3 +16,28 @@ To (re)build documentation for all the SIGs, run these commands:
 ```bash
 make all
 ```
+
+## Adding custom content to your SIG's README
+
+If your SIG wishes to add custom content, you can do so by placing it within
+the following code comments:
+
+```markdown
+<!-- BEGIN CUSTOM CONTENT -->
+
+<!-- END CUSTOM CONTENT -->
+```
+
+Anything inside these code comments are saved by the generator and appended
+to newly generated content. Updating any content outside this block, however,
+will be overwritten the next time the generator runs.
+
+An example might be:
+
+```markdown
+<!-- BEGIN CUSTOM CONTENT -->
+## Upcoming SIG goals
+- Do this
+- Do that
+<!-- END CUSTOM CONTENT -->
+```

generator/app.go

@@ -31,15 +31,17 @@ import (
 )
 
 var (
-	sigsYamlFile    = "sigs.yaml"
-	templateDir     = "generator"
-	indexTemplate   = filepath.Join(templateDir, "sig_index.tmpl")
-	listTemplate    = filepath.Join(templateDir, "sig_list.tmpl")
-	headerTemplate  = filepath.Join(templateDir, "header.tmpl")
-	footerTemplate  = filepath.Join(templateDir, "footer.tmpl")
-	sigListOutput   = "sig-list.md"
-	sigIndexOutput  = "README.md"
-	githubTeamNames = []string{"misc", "test-failures", "bugs", "feature-requests", "proposals", "pr-reviews", "api-reviews"}
+	sigsYamlFile        = "sigs.yaml"
+	templateDir         = "generator"
+	indexTemplate       = filepath.Join(templateDir, "sig_index.tmpl")
+	listTemplate        = filepath.Join(templateDir, "sig_list.tmpl")
+	headerTemplate      = filepath.Join(templateDir, "header.tmpl")
+	sigListOutput       = "sig-list.md"
+	sigIndexOutput      = "README.md"
+	githubTeamNames     = []string{"misc", "test-failures", "bugs", "feature-requests", "proposals", "pr-reviews", "api-reviews"}
+	beginMarker         = "<!-- BEGIN CUSTOM CONTENT -->"
+	endMarker           = "<!-- END CUSTOM CONTENT -->"
+	lastGeneratedPrefix = "Last generated: "
 )
 
 type Lead struct {
@@ -64,7 +66,6 @@ type Contact struct {
 }
 
 type Sig struct {
-	Page
 	Name              string
 	Dir               string
 	MissionStatement  string `yaml:"mission_statement"`
@@ -76,14 +77,9 @@ type Sig struct {
 }
 
 type SigEntries struct {
-	Page
 	Sigs []Sig
 }
 
-type Page struct {
-	LastGenerated string
-}
-
 func (slice SigEntries) Len() int {
 	return len(slice.Sigs)
 }
@@ -105,33 +101,81 @@ func createDirIfNotExists(path string) error {
 	return nil
 }
 
+func getExistingContent(path string) (string, error) {
+	capture := false
+	var captured []string
+
+	// NOTE: For some reason using bufio.Scanner with existing file pointer prepends
+	// a bunch of null ^@ characters, so using to ioutil.ReadFile instead.
+	content, err := ioutil.ReadFile(path)
+	if err != nil {
+		return "", err
+	}
+
+	for _, line := range strings.Split(string(content), "\n") {
+		if strings.Contains(line, endMarker) {
+			capture = false
+		}
+		if capture {
+			captured = append(captured, line)
+		}
+		if strings.Contains(line, beginMarker) {
+			capture = true
+		}
+	}
+
+	return strings.Join(captured, "\n"), nil
+}
+
 func writeTemplate(templatePath, outputPath string, data interface{}) error {
 	// set up template
-	t, err := template.ParseFiles(templatePath, headerTemplate, footerTemplate)
+	t, err := template.ParseFiles(templatePath, headerTemplate)
 	if err != nil {
 		return err
 	}
 
 	// open file and truncate
-	f, err := os.OpenFile(outputPath, os.O_WRONLY, 0644)
+	f, err := os.OpenFile(outputPath, os.O_RDWR, 0644)
 	if err != nil {
 		return err
 	}
 	defer f.Close()
+
+	// get any existing content
+	content, err := getExistingContent(outputPath)
+	if err != nil {
+		return err
+	}
+
+	// ensure file is empty
 	f.Truncate(0)
 
-	// write template output to file
+	// generated content
 	err = t.Execute(f, data)
 	if err != nil {
 		return err
 	}
 
+	// custom content block
+	writeCustomContentBlock(f, content)
+
+	// last generated
+	writeLastGenerated(f)
+
 	fmt.Printf("Generated %s\n", outputPath)
 	return nil
 }
 
-func lastGenerated() string {
-	return time.Now().Format("Mon Jan 2 2006 15:04:05")
+func writeCustomContentBlock(f *os.File, content string) {
+	lines := []string{beginMarker, "\n", content, "\n", endMarker, "\n"}
+	for _, line := range lines {
+		f.Write([]byte(line))
+	}
+}
+
+func writeLastGenerated(f *os.File) {
+	lastGenerated := fmt.Sprintf("\n%s %s", lastGeneratedPrefix, time.Now().Format("Mon Jan 2 2006 15:04:05"))
+	f.Write([]byte(lastGenerated))
 }
 
 func createReadmeFiles(ctx SigEntries) error {
@@ -140,8 +184,6 @@ func createReadmeFiles(ctx SigEntries) error {
 
 		createDirIfNotExists(dirName)
 
-		sig.LastGenerated = lastGenerated()
-
 		prefix := sig.Contact.GithubTeamPrefix
 		if prefix == "" {
 			prefix = dirName
@@ -161,7 +203,6 @@ func createReadmeFiles(ctx SigEntries) error {
 }
 
 func createListFile(ctx SigEntries) error {
-	ctx.LastGenerated = lastGenerated()
 	return writeTemplate(listTemplate, sigListOutput, ctx)
 }
 

generator/footer.tmpl

@@ -1,3 +0,0 @@
-{{- define "footer" -}}
-Last generated: {{.LastGenerated}}
-{{- end -}}

generator/sig_index.tmpl

@@ -23,5 +23,3 @@ Meeting notes and Agenda can be found [here]({{.MeetingArchiveURL}}).
 * [@{{.}}](https://github.com/kubernetes/teams/{{.}})
 {{end}}
 {{end}}
-
-{{template "footer" . }}

generator/sig_list.tmpl

@@ -18,5 +18,3 @@ When the need arises, a [new SIG can be created](sig-creation-procedure.md)
 {{- range .Sigs}}
 |[{{.Name}}]({{.Dir}}/README.md)|{{range .Leads}}* [{{.Name}}](https://github.com/{{.GitHub}}){{if .Company}}, {{.Company}}{{end}}<br>{{end}}|* [Slack](https://kubernetes.slack.com/messages/{{.Contact.Slack}})<br>* [Mailing List]({{.Contact.MailingList}})|{{ $save := . }}{{range .Meetings}}* [{{.Day}}s at {{.UTC}} UTC ({{.Frequency}})]({{$save.MeetingURL}})<br>{{end}}
 {{- end }}
-
-{{ template "footer" . }}