diff options
| -rw-r--r-- | plugin.md | 2 | ||||
| -rw-r--r-- | plugin/cancel/README.md | 2 | ||||
| -rw-r--r-- | plugin/k8s_external/README.md | 2 | ||||
| -rw-r--r-- | plugin/rewrite/README.md | 2 | ||||
| -rw-r--r-- | plugin/secondary/README.md | 2 | ||||
| -rw-r--r-- | plugin/transfer/README.md | 4 | ||||
| -rw-r--r-- | test/readme_test.go | 50 |
7 files changed, 62 insertions, 2 deletions
@@ -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. diff --git a/plugin/cancel/README.md b/plugin/cancel/README.md index 8561b1f6b..65224bf52 100644 --- a/plugin/cancel/README.md +++ b/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] ~~~ diff --git a/plugin/k8s_external/README.md b/plugin/k8s_external/README.md index dc251ab02..9fded952a 100644 --- a/plugin/k8s_external/README.md +++ b/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. diff --git a/plugin/rewrite/README.md b/plugin/rewrite/README.md index 601bf0447..ca48a6d17 100644 --- a/plugin/rewrite/README.md +++ b/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 diff --git a/plugin/secondary/README.md b/plugin/secondary/README.md index 00a9d6b88..dab740284 100644 --- a/plugin/secondary/README.md +++ b/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...] ~~~ diff --git a/plugin/transfer/README.md b/plugin/transfer/README.md index 45ec60c99..fdd4467d2 100644 --- a/plugin/transfer/README.md +++ b/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 diff --git a/test/readme_test.go b/test/readme_test.go index b857def12..38fbcc0e2 100644 --- a/test/readme_test.go +++ b/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) |