Use a common set of tag prefixes for munges

All munges now start with `<!-- BEGIN MUNGE:` and end with `<!-- END MUNGE:`. This lets me (in a followup) filter them better to normalize contents during verification of generated docs.
penland365 · Jul 13, 2015 · ad8f873 · ad8f873
1 parent 8fceb75
commit ad8f873
Show file tree

Hide file tree

Showing 5 changed files with 36 additions and 13 deletions.
diff --git a/cmd/mungedocs/toc.go b/cmd/mungedocs/toc.go
@@ -23,10 +23,12 @@ import (
 	"strings"
 )
 
+const tocMungeTag = "GENERATED_TOC"
+
 // inserts/updates a table of contents in markdown file.
 //
 // First, builds a ToC.
-// Then, finds <!-- BEGIN GENERATED TOC --> and <!-- END GENERATED TOC -->, and replaces anything between those with
+// Then, finds the magic macro block tags and replaces anything between those with
 // the ToC, thereby updating any previously inserted ToC.
 //
 // TODO(erictune): put this in own package with tests
@@ -36,7 +38,7 @@ func updateTOC(filePath string, markdown []byte) ([]byte, error) {
 		return nil, err
 	}
 	lines := splitLines(markdown)
-	updatedMarkdown, err := updateMacroBlock(lines, "<!-- BEGIN GENERATED TOC -->", "<!-- END GENERATED TOC -->", string(toc))
+	updatedMarkdown, err := updateMacroBlock(lines, beginMungeTag(tocMungeTag), endMungeTag(tocMungeTag), string(toc))
 	if err != nil {
 		return nil, err
 	}

diff --git a/cmd/mungedocs/toc_test.go b/cmd/mungedocs/toc_test.go
@@ -29,8 +29,10 @@ func Test_buildTOC(t *testing.T) {
 	}{
 		{"", ""},
 		{"Lorem ipsum\ndolor sit amet\n", ""},
-		{"# Title\nLorem ipsum \n## Section Heading\ndolor sit amet\n",
-			"- [Title](#title)\n  - [Section Heading](#section-heading)\n"},
+		{
+			"# Title\nLorem ipsum \n## Section Heading\ndolor sit amet\n",
+			"- [Title](#title)\n  - [Section Heading](#section-heading)\n",
+		},
 	}
 	for _, c := range cases {
 		actual, err := buildTOC([]byte(c.in))
@@ -47,10 +49,14 @@ func Test_updateTOC(t *testing.T) {
 		out string
 	}{
 		{"", ""},
-		{"Lorem ipsum\ndolor sit amet\n",
-			"Lorem ipsum\ndolor sit amet\n"},
-		{"# Title\nLorem ipsum \n**table of contents**\n<!-- BEGIN GENERATED TOC -->\nold cruft\n<!-- END GENERATED TOC -->\n## Section Heading\ndolor sit amet\n",
-			"# Title\nLorem ipsum \n**table of contents**\n<!-- BEGIN GENERATED TOC -->\n- [Title](#title)\n  - [Section Heading](#section-heading)\n\n<!-- END GENERATED TOC -->\n## Section Heading\ndolor sit amet\n"},
+		{
+			"Lorem ipsum\ndolor sit amet\n",
+			"Lorem ipsum\ndolor sit amet\n",
+		},
+		{
+			"# Title\nLorem ipsum \n**table of contents**\n<!-- BEGIN MUNGE: GENERATED_TOC -->\nold cruft\n<!-- END MUNGE: GENERATED_TOC -->\n## Section Heading\ndolor sit amet\n",
+			"# Title\nLorem ipsum \n**table of contents**\n<!-- BEGIN MUNGE: GENERATED_TOC -->\n- [Title](#title)\n  - [Section Heading](#section-heading)\n\n<!-- END MUNGE: GENERATED_TOC -->\n## Section Heading\ndolor sit amet\n",
+		},
 	}
 	for _, c := range cases {
 		actual, err := updateTOC("filename.md", []byte(c.in))

diff --git a/cmd/mungedocs/unversioned_warning.go b/cmd/mungedocs/unversioned_warning.go
@@ -16,9 +16,12 @@ limitations under the License.
 
 package main
 
-var beginUnversionedWarning = "<!-- BEGIN UNVERSIONED_WARNING -->"
-var endUnversionedWarning = "<!-- END UNVERSIONED_WARNING -->"
-var unversionedWarning = `
+const unversionedWarningTag = "UNVERSIONED_WARNING"
+
+var beginUnversionedWarning = beginMungeTag(unversionedWarningTag)
+var endUnversionedWarning = endMungeTag(unversionedWarningTag)
+
+const unversionedWarning = `
 <!-- BEGIN STRIP_FOR_RELEASE -->
 
 <h1>*** PLEASE NOTE: This document applies to the HEAD of the source

diff --git a/cmd/mungedocs/util.go b/cmd/mungedocs/util.go
@@ -98,3 +98,15 @@ func hasMacroBlock(lines []string, begin string, end string) bool {
 	}
 	return false
 }
+
+// Returns the canonical begin-tag for a given description.  This does not
+// include the trailing newline.
+func beginMungeTag(desc string) string {
+	return fmt.Sprintf("<!-- BEGIN MUNGE: %s -->", desc)
+}
+
+// Returns the canonical end-tag for a given description.  This does not
+// include the trailing newline.
+func endMungeTag(desc string) string {
+	return fmt.Sprintf("<!-- END MUNGE: %s -->", desc)
+}
diff --git a/docs/networking.md b/docs/networking.md
@@ -1,6 +1,6 @@
 # Networking in Kubernetes
 **Table of Contents**
-<!-- BEGIN GENERATED TOC -->
+<!-- BEGIN MUNGE: GENERATED_TOC -->
 - [Networking in Kubernetes](#networking-in-kubernetes)
   - [Summary](#summary)
   - [Docker model](#docker-model)
@@ -14,7 +14,7 @@
     - [Calico](#calico)
   - [Other reading](#other-reading)
 
-<!-- END GENERATED TOC -->
+<!-- END MUNGE: GENERATED_TOC -->
 
 Kubernetes approaches networking somewhat differently than Docker does by
 default.  There are 4 distinct networking problems to solve: