Make munger begin/end less generic

Just force the beginMungeTag() endMungeTag() macros on users, by hiding
it under the covers. It really simplies things for users.

Author: eparis

cmd/mungedocs/toc.go

@@ -39,7 +39,7 @@ func updateTOC(filePath string, markdown []byte) ([]byte, error) {
 		return nil, err
 	}
 	lines := splitLines(markdown)
-	updatedMarkdown, err := updateMacroBlock(lines, beginMungeTag(tocMungeTag), endMungeTag(tocMungeTag), string(toc))
+	updatedMarkdown, err := updateMacroBlock(lines, tocMungeTag, string(toc))
 	if err != nil {
 		return nil, err
 	}

cmd/mungedocs/unversioned_warning.go

@@ -20,9 +20,6 @@ import "fmt"
 
 const unversionedWarningTag = "UNVERSIONED_WARNING"
 
-var beginUnversionedWarning = beginMungeTag(unversionedWarningTag)
-var endUnversionedWarning = endMungeTag(unversionedWarningTag)
-
 const unversionedWarningFmt = `
 <!-- BEGIN STRIP_FOR_RELEASE -->
 
@@ -65,8 +62,8 @@ func updateUnversionedWarning(file string, markdown []byte) ([]byte, error) {
 		// No warnings on release branches
 		return markdown, nil
 	}
-	if !hasMacroBlock(lines, beginUnversionedWarning, endUnversionedWarning) {
-		lines = append([]string{beginUnversionedWarning, endUnversionedWarning}, lines...)
+	if !hasMacroBlock(lines, unversionedWarningTag) {
+		lines = prependMacroBlock(unversionedWarningTag, lines)
 	}
-	return updateMacroBlock(lines, beginUnversionedWarning, endUnversionedWarning, makeUnversionedWarning(file))
+	return updateMacroBlock(lines, unversionedWarningTag, makeUnversionedWarning(file))
 }

cmd/mungedocs/unversioned_warning_test.go

@@ -23,7 +23,10 @@ import (
 )
 
 func TestUnversionedWarning(t *testing.T) {
-	warningBlock := beginUnversionedWarning + "\n" + makeUnversionedWarning("filename.md") + "\n" + endUnversionedWarning + "\n"
+	beginMark := beginMungeTag(unversionedWarningTag)
+	endMark := endMungeTag(unversionedWarningTag)
+
+	warningBlock := beginMark + "\n" + makeUnversionedWarning("filename.md") + "\n" + endMark + "\n"
 	var cases = []struct {
 		in  string
 		out string
@@ -38,15 +41,15 @@ func TestUnversionedWarning(t *testing.T) {
 			"Foo\n<!-- TAG IS_VERSIONED -->\nBar",
 		},
 		{
-			beginUnversionedWarning + "\n" + endUnversionedWarning + "\n",
+			beginMark + "\n" + endMark + "\n",
 			warningBlock,
 		},
 		{
-			beginUnversionedWarning + "\n" + "something\n" + endUnversionedWarning + "\n",
+			beginMark + "\n" + "something\n" + endMark + "\n",
 			warningBlock,
 		},
 		{
-			"Foo\n" + beginUnversionedWarning + "\n" + endUnversionedWarning + "\nBar\n",
+			"Foo\n" + beginMark + "\n" + endMark + "\nBar\n",
 			"Foo\n" + warningBlock + "Bar\n",
 		},
 		{

cmd/mungedocs/util.go

@@ -38,7 +38,9 @@ func splitLines(document []byte) []string {
 //
 // Delimiters should occupy own line.
 // Returns copy of document with modifications.
-func updateMacroBlock(lines []string, beginMark, endMark, insertThis string) ([]byte, error) {
+func updateMacroBlock(lines []string, token, insertThis string) ([]byte, error) {
+	beginMark := beginMungeTag(token)
+	endMark := endMungeTag(token)
 	var buffer bytes.Buffer
 	betweenBeginAndEnd := false
 	for _, line := range lines {
@@ -85,15 +87,32 @@ func hasLine(lines []string, needle string) bool {
 	return false
 }
 
+// Add a macro block to the beginning of a set of lines
+func prependMacroBlock(token string, lines []string) []string {
+	beginMark := beginMungeTag(token)
+	endMark := endMungeTag(token)
+	return append([]string{beginMark, endMark}, lines...)
+}
+
+// Add a macro block to the end of a set of lines
+func appendMacroBlock(token string, lines []string) []string {
+	beginMark := beginMungeTag(token)
+	endMark := endMungeTag(token)
+	return append(lines, beginMark, endMark)
+}
+
 // Tests that a document, represented as a slice of lines, has a macro block.
-func hasMacroBlock(lines []string, begin string, end string) bool {
+func hasMacroBlock(lines []string, token string) bool {
+	beginMark := beginMungeTag(token)
+	endMark := endMungeTag(token)
+
 	foundBegin := false
 	for _, line := range lines {
 		trimmedLine := strings.Trim(line, " \n")
 		switch {
-		case !foundBegin && trimmedLine == begin:
+		case !foundBegin && trimmedLine == beginMark:
 			foundBegin = true
-		case foundBegin && trimmedLine == end:
+		case foundBegin && trimmedLine == endMark:
 			return true
 		}
 	}

cmd/mungedocs/util_test.go

@@ -24,18 +24,22 @@ import (
 )
 
 func Test_updateMacroBlock(t *testing.T) {
+	token := "TOKEN"
+	BEGIN := beginMungeTag(token)
+	END := endMungeTag(token)
+
 	var cases = []struct {
 		in  string
 		out string
 	}{
 		{"", ""},
 		{"Lorem ipsum\ndolor sit amet\n",
 			"Lorem ipsum\ndolor sit amet\n"},
-		{"Lorem ipsum \n BEGIN\ndolor\nEND\nsit amet\n",
-			"Lorem ipsum \n BEGIN\nfoo\n\nEND\nsit amet\n"},
+		{"Lorem ipsum \n " + BEGIN + "\ndolor\n" + END + "\nsit amet\n",
+			"Lorem ipsum \n " + BEGIN + "\nfoo\n\n" + END + "\nsit amet\n"},
 	}
 	for _, c := range cases {
-		actual, err := updateMacroBlock(splitLines([]byte(c.in)), "BEGIN", "END", "foo\n")
+		actual, err := updateMacroBlock(splitLines([]byte(c.in)), "TOKEN", "foo\n")
 		assert.NoError(t, err)
 		if c.out != string(actual) {
 			t.Errorf("Expected '%v' but got '%v'", c.out, string(actual))
@@ -44,20 +48,23 @@ func Test_updateMacroBlock(t *testing.T) {
 }
 
 func Test_updateMacroBlock_errors(t *testing.T) {
+	b := beginMungeTag("TOKEN")
+	e := endMungeTag("TOKEN")
+
 	var cases = []struct {
 		in string
 	}{
-		{"BEGIN\n"},
-		{"blah\nBEGIN\nblah"},
-		{"END\n"},
-		{"blah\nEND\nblah\n"},
-		{"END\nBEGIN"},
-		{"BEGIN\nEND\nEND"},
-		{"BEGIN\nBEGIN\nEND"},
-		{"BEGIN\nBEGIN\nEND\nEND"},
+		{b + "\n"},
+		{"blah\n" + b + "\nblah"},
+		{e + "\n"},
+		{"blah\n" + e + "\nblah\n"},
+		{e + "\n" + b},
+		{b + "\n" + e + "\n" + e},
+		{b + "\n" + b + "\n" + e},
+		{b + "\n" + b + "\n" + e + "\n" + e},
 	}
 	for _, c := range cases {
-		_, err := updateMacroBlock(splitLines([]byte(c.in)), "BEGIN", "END", "foo")
+		_, err := updateMacroBlock(splitLines([]byte(c.in)), "TOKEN", "foo")
 		assert.Error(t, err)
 	}
 }
@@ -86,26 +93,27 @@ func TestHasLine(t *testing.T) {
 }
 
 func TestHasMacroBlock(t *testing.T) {
+	token := "<<<"
+	b := beginMungeTag(token)
+	e := endMungeTag(token)
 	cases := []struct {
 		lines    []string
-		begin    string
-		end      string
 		expected bool
 	}{
-		{[]string{"<<<", ">>>"}, "<<<", ">>>", true},
-		{[]string{"<<<", "abc", ">>>"}, "<<<", ">>>", true},
-		{[]string{"<<<", "<<<", "abc", ">>>"}, "<<<", ">>>", true},
-		{[]string{"<<<", "abc", ">>>", ">>>"}, "<<<", ">>>", true},
-		{[]string{"<<<", ">>>", "<<<", ">>>"}, "<<<", ">>>", true},
-		{[]string{"<<<"}, "<<<", ">>>", false},
-		{[]string{">>>"}, "<<<", ">>>", false},
-		{[]string{"<<<", "abc"}, "<<<", ">>>", false},
-		{[]string{"abc", ">>>"}, "<<<", ">>>", false},
+		{[]string{b, e}, true},
+		{[]string{b, "abc", e}, true},
+		{[]string{b, b, "abc", e}, true},
+		{[]string{b, "abc", e, e}, true},
+		{[]string{b, e, b, e}, true},
+		{[]string{b}, false},
+		{[]string{e}, false},
+		{[]string{b, "abc"}, false},
+		{[]string{"abc", e}, false},
 	}
 
 	for i, c := range cases {
-		if hasMacroBlock(c.lines, c.begin, c.end) != c.expected {
-			t.Errorf("case[%d]: %q,%q, expected %t, got %t", i, c.begin, c.end, c.expected, !c.expected)
+		if hasMacroBlock(c.lines, token) != c.expected {
+			t.Errorf("case[%d]: expected %t, got %t", i, c.expected, !c.expected)
 		}
 	}
 }

docs/admin/namespaces/README.md

@@ -99,7 +99,7 @@ Use the file [`namespace-dev.json`](namespace-dev.json) which describes a develo
 ```
 
 [Download example](namespace-dev.json)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE namespace-dev.json -->
 
 Create the development namespace using kubectl.
 

docs/getting-started-guides/logging.md

@@ -74,7 +74,7 @@ spec:
 ```
 
 [Download example](../../examples/blog-logging/counter-pod.yaml)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE ../../examples/blog-logging/counter-pod.yaml -->
 
 This pod specification has one container which runs a bash script when the container is born. This script simply writes out the value of a counter and the date once per second and runs indefinitely. Let’s create the pod in the default
 namespace.
@@ -192,7 +192,7 @@ spec:
 ```
 
 [Download example](../../cluster/saltbase/salt/fluentd-gcp/fluentd-gcp.yaml)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE ../../cluster/saltbase/salt/fluentd-gcp/fluentd-gcp.yaml -->
 
 This pod specification maps the directory on the host containing the Docker log files, `/var/lib/docker/containers`, to a directory inside the container which has the same path. The pod runs one image, `gcr.io/google_containers/fluentd-gcp:1.6`, which is configured to collect the Docker log files from the logs directory and ingest them into Google Cloud Logging. One instance of this pod runs on each node of the cluster. Kubernetes will notice if this pod fails and automatically restart it.
 

docs/user-guide/downward-api.md

@@ -105,7 +105,7 @@ spec:
 ```
 
 [Download example](downward-api/dapi-pod.yaml)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE downward-api/dapi-pod.yaml -->
 
 Some more thorough examples:
    * [environment variables](environment-guide/)

docs/user-guide/logging.md

@@ -59,7 +59,7 @@ spec:
 ```
 
 [Download example](../../examples/blog-logging/counter-pod.yaml)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE ../../examples/blog-logging/counter-pod.yaml -->
 
 we can run the pod:
 

docs/user-guide/simple-yaml.md

@@ -65,7 +65,7 @@ spec:
 ```
 
 [Download example](pod.yaml)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE pod.yaml -->
 
 You can see your cluster's pods:
 
@@ -117,7 +117,7 @@ spec:
 ```
 
 [Download example](replication.yaml)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE replication.yaml -->
 
 To delete the replication controller (and the pods it created):
 

docs/user-guide/walkthrough/README.md

@@ -166,7 +166,7 @@ spec:
 ```
 
 [Download example](pod-redis.yaml)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE pod-redis.yaml -->
 
 Notes:
 - The volume mount name is a reference to a specific empty dir volume.

docs/user-guide/walkthrough/k8s201.md

@@ -87,7 +87,7 @@ spec:
 ```
 
 [Download example](pod-nginx-with-label.yaml)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE pod-nginx-with-label.yaml -->
 
 Create the labeled pod ([pod-nginx-with-label.yaml](pod-nginx-with-label.yaml)):
 
@@ -143,7 +143,7 @@ spec:
 ```
 
 [Download example](replication-controller.yaml)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE replication-controller.yaml -->
 
 #### Replication Controller Management
 
@@ -196,7 +196,7 @@ spec:
 ```
 
 [Download example](service.yaml)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE service.yaml -->
 
 #### Service Management
 
@@ -312,7 +312,7 @@ spec:
 ```
 
 [Download example](pod-with-http-healthcheck.yaml)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE pod-with-http-healthcheck.yaml -->
 
 For more information about health checking, see [Container Probes](../pod-states.md#container-probes).
 

examples/cassandra/README.md

@@ -101,7 +101,7 @@ spec:
 ```
 
 [Download example](cassandra-controller.yaml)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE cassandra-controller.yaml -->
 
 There are a few things to note in this description.  First is that we are running the ```kubernetes/cassandra``` image.  This is a standard Cassandra installation on top of Debian.  However it also adds a custom [```SeedProvider```](https://svn.apache.org/repos/asf/cassandra/trunk/src/java/org/apache/cassandra/locator/SeedProvider.java) to Cassandra.  In Cassandra, a ```SeedProvider``` bootstraps the gossip protocol that Cassandra uses to find other nodes.  The ```KubernetesSeedProvider``` discovers the Kubernetes API Server using the built in Kubernetes discovery service, and then uses the Kubernetes API to find new nodes (more on this later)
 
@@ -132,7 +132,7 @@ spec:
 ```
 
 [Download example](cassandra-service.yaml)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE cassandra-service.yaml -->
 
 The important thing to note here is the ```selector```. It is a query over labels, that identifies the set of _Pods_ contained by the _Service_.  In this case the selector is ```name=cassandra```.  If you look back at the Pod specification above, you'll see that the pod has the corresponding label, so it will be selected for membership in this Service.
 
@@ -242,7 +242,7 @@ spec:
 ```
 
 [Download example](cassandra-controller.yaml)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE cassandra-controller.yaml -->
 
 Most of this replication controller definition is identical to the Cassandra pod definition above, it simply gives the resplication controller a recipe to use when it creates new Cassandra pods.  The other differentiating parts are the ```selector``` attribute which contains the controller's selector query, and the ```replicas``` attribute which specifies the desired number of replicas, in this case 1.
 

examples/celery-rabbitmq/README.md

@@ -82,7 +82,7 @@ spec:
 ```
 
 [Download example](rabbitmq-service.yaml)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE rabbitmq-service.yaml -->
 
 To start the service, run:
 
@@ -127,7 +127,7 @@ spec:
 ```
 
 [Download example](rabbitmq-controller.yaml)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE rabbitmq-controller.yaml -->
 
 Running `$ kubectl create -f examples/celery-rabbitmq/rabbitmq-controller.yaml` brings up a replication controller that ensures one pod exists which is running a RabbitMQ instance.
 
@@ -168,7 +168,7 @@ spec:
 ```
 
 [Download example](celery-controller.yaml)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE celery-controller.yaml -->
 
 There are several things to point out here...
 
@@ -239,7 +239,7 @@ spec:
 ```
 
 [Download example](flower-service.yaml)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE flower-service.yaml -->
 
 It is marked as external (LoadBalanced). However on many platforms you will have to add an explicit firewall rule to open port 5555.
 On GCE this can be done with:
@@ -280,7 +280,7 @@ spec:
 ```
 
 [Download example](flower-controller.yaml)
-<!-- END MUNGE: EXAMPLE -->
+<!-- END MUNGE: EXAMPLE flower-controller.yaml -->
 
 This will bring up a new pod with Flower installed and port 5555 (Flower's default port) exposed through the service endpoint. This image uses the following command to start Flower: