presubmit: test README.md sections (#3644)

Automatically submitted.

plugin.md

@@ -75,7 +75,7 @@ Each plugin should have a README.md explaining what the plugin does and how it i
 file should have the following layout:
 
 * Title: use the plugin's name
-* Subsection titled: "Named"
+* Subsection titled: "Name"
     with *PLUGIN* - one line description.
 * Subsection titled: "Description" has a longer description.
 * Subsection titled: "Syntax", syntax and supported directives.

plugin/cancel/README.md

@@ -16,6 +16,8 @@ A plugin interested in the cancellation status should call `plugin.Done()` on th
 context was canceled due to a timeout the plugin should not write anything back to the client and
 return a value indicating CoreDNS should not either; a zero return value should suffice for that.
 
+## Syntax
+
 ~~~ txt
 cancel [TIMEOUT]
 ~~~

plugin/k8s_external/README.md

@@ -57,7 +57,7 @@ k8s_external [ZONE...] {
 * **APEX** is the name (DNS label) to use for the apex records; it defaults to `dns`.
 * `ttl` allows you to set a custom **TTL** for responses. The default is 5 (seconds).
 
-# Examples
+## Examples
 
 Enable names under `example.org` to be resolved to in-cluster DNS addresses.
 

plugin/rewrite/README.md

@@ -37,6 +37,8 @@ will behave as follows:
    * `continue` will continue applying the next rule in the rule list.
    * `stop` will consider the current rule the last rule and will not continue.  The default behaviour is `stop`
 
+## Examples
+
 ### Name Field Rewrites
 
 The `rewrite` plugin offers the ability to match the name in the question section of

plugin/secondary/README.md

@@ -10,6 +10,8 @@ With *secondary* you can transfer (via AXFR) a zone from another server. The ret
 *not committed* to disk (a violation of the RFC). This means restarting CoreDNS will cause it to
 retrieve all secondary zones.
 
+## Syntax
+
 ~~~
 secondary [ZONES...]
 ~~~

plugin/transfer/README.md

@@ -29,3 +29,7 @@ transfer [ZONE...] {
 
 * `to ` **HOST...** The hosts *transfer* will transfer to. Use `*` to permit
   transfers to all hosts.
+
+## Examples
+
+TODO

test/readme_test.go

@@ -2,10 +2,12 @@ package test
 
 import (
 	"bufio"
+	"fmt"
 	"io/ioutil"
 	"os"
 	"path/filepath"
 	"strconv"
+	"strings"
 	"testing"
 
 	"github.com/coredns/coredns/core/dnsserver"
@@ -39,6 +41,9 @@ PrivateKey: f03VplaIEA+KHI9uizlemUSbUJH86hPBPjmcUninPoM=
 //	# check-this-please
 // }
 // ~~~
+//
+// While we're at it - we also check the README.md itself. It should at least have the sections:
+// Name, Description, Syntax and Examples. See plugin.md for more details.
 func TestReadme(t *testing.T) {
 	port := 30053
 	caddy.Quiet = true
@@ -59,6 +64,10 @@ func TestReadme(t *testing.T) {
 		readme := filepath.Join(middle, d.Name())
 		readme = filepath.Join(readme, "README.md")
 
+		if err := sectionsFromReadme(readme); err != nil {
+			t.Fatal(err)
+		}
+
 		inputs, err := corefileFromReadme(readme)
 		if err != nil {
 			continue
@@ -118,6 +127,47 @@ func corefileFromReadme(readme string) ([]*Input, error) {
 	return input, nil
 }
 
+// sectionsFromReadme returns an error if the readme doesn't contains all
+// mandatory sections. The check is basic, as we match each line, this mostly
+// works, because markdown is such a simple format.
+// We want: Name, Description, Syntax, Examples - in this order.
+func sectionsFromReadme(readme string) error {
+	f, err := os.Open(readme)
+	if err != nil {
+		return nil // don't error when we can read the file
+	}
+	defer f.Close()
+
+	section := 0
+	s := bufio.NewScanner(f)
+	for s.Scan() {
+		line := s.Text()
+		switch section {
+		case 0:
+			if strings.HasPrefix(line, "## Name") {
+				section++
+			}
+		case 1:
+			if strings.HasPrefix(line, "## Description") {
+				section++
+			}
+		case 2:
+			if strings.HasPrefix(line, "## Syntax") {
+				section++
+			}
+		case 3:
+			if strings.HasPrefix(line, "## Examples") {
+				section++
+			}
+		}
+	}
+	if section != 4 {
+		return fmt.Errorf("Sections incomplete or ordered wrong: %q, want (at least): Name, Descripion, Syntax and Examples", readme)
+	}
+	return nil
+
+}
+
 func create(c map[string]string) {
 	for name, content := range c {
 		ioutil.WriteFile(name, []byte(content), 0644)