Fix linter and add tests

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

.github/workflows/godev.yml

@@ -0,0 +1,23 @@
+name: godev
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Set up Go
+        uses: actions/setup-go@v2
+        with:
+          go-version: 1.16
+      -
+        name: Call pkg.go.dev
+        run: |
+          go get github.com/${GITHUB_REPOSITORY}@${GITHUB_REF#refs/tags/}
+        env:
+          GO111MODULE: on
+          GOPROXY: https://proxy.golang.org

example/go.mod

@@ -3,15 +3,15 @@ module github.com/docker/yamldocs/example
 go 1.16
 
 require (
-	github.com/docker/yamldocs v0.0.0
 	github.com/docker/buildx v0.6.0
 	github.com/docker/cli v20.10.7+incompatible
+	github.com/docker/yamldocs v0.0.0
 	github.com/spf13/cobra v1.2.1
 	github.com/spf13/pflag v1.0.5
 )
 
 replace (
-	github.com/docker/yamldocs => ../
 	github.com/docker/cli => github.com/docker/cli v20.10.3-0.20210702143511-f782d1355eff+incompatible
 	github.com/docker/docker => github.com/docker/docker v20.10.3-0.20210609100121-ef4d47340142+incompatible
+	github.com/docker/yamldocs => ../
 )

hack/lint.Dockerfile

@@ -3,6 +3,7 @@ ARG GO_VERSION
 
 FROM golang:${GO_VERSION}-alpine AS base
 RUN apk add --no-cache linux-headers
+ENV CGO_ENABLED=0
 WORKDIR /src
 
 FROM golangci/golangci-lint:v1.37-alpine AS golangci-lint

hack/test.Dockerfile

@@ -3,6 +3,7 @@ ARG GO_VERSION
 
 FROM golang:${GO_VERSION}-alpine AS base
 RUN apk add --no-cache gcc linux-headers musl-dev
+ENV CGO_ENABLED=0
 WORKDIR /src
 
 FROM base AS gomod
@@ -14,7 +15,7 @@ FROM gomod AS test
 RUN --mount=type=bind,target=. \
   --mount=type=cache,target=/go/pkg/mod \
   --mount=type=cache,target=/root/.cache/go-build \
-  go test -v -coverprofile=/tmp/coverage.txt -covermode=atomic -race ./...
+  go test -v -coverprofile=/tmp/coverage.txt -covermode=atomic ./...
 
 FROM scratch AS test-coverage
 COPY --from=test /tmp/coverage.txt /coverage.txt

yamldocs.go

@@ -10,7 +10,7 @@ import (
 
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
-	yaml "gopkg.in/yaml.v2"
+	"gopkg.in/yaml.v2"
 )
 
 type cmdOption struct {
@@ -53,13 +53,17 @@ type cmdDoc struct {
 	OSType           string `yaml:"os_type,omitempty"`
 }
 
-// GenYamlTree creates yaml structured ref files
+// GenYamlTree creates yaml structured ref files for this command and all descendants
+// in the directory given. This function may not work
+// correctly if your command names have `-` in them. If you have `cmd` with two
+// subcmds, `sub` and `sub-third`, and `sub` has a subcommand called `third`
+// it is undefined which help output will be in the file `cmd-sub-third.1`.
 func GenYamlTree(cmd *cobra.Command, dir string) error {
 	emptyStr := func(s string) string { return "" }
 	return GenYamlTreeCustom(cmd, dir, emptyStr)
 }
 
-// GenYamlTreeCustom creates yaml structured ref files
+// GenYamlTreeCustom creates yaml structured ref files.
 func GenYamlTreeCustom(cmd *cobra.Command, dir string, filePrepender func(string) string) error {
 	for _, c := range cmd.Commands() {
 		if !c.Runnable() && !c.HasAvailableSubCommands() {
@@ -104,7 +108,7 @@ func GenYamlTreeCustom(cmd *cobra.Command, dir string, filePrepender func(string
 	return GenYamlCustom(cmd, f)
 }
 
-// GenYamlCustom creates custom yaml output
+// GenYamlCustom creates custom yaml output.
 // nolint: gocyclo
 func GenYamlCustom(cmd *cobra.Command, w io.Writer) error {
 	const (
@@ -314,9 +318,9 @@ func hasSeeAlso(cmd *cobra.Command) bool {
 	return false
 }
 
-// applyDescriptionAndExamples fills in cmd.Long and cmd.Example with the
+// ApplyDescriptionAndExamples fills in cmd.Long and cmd.Example with the
 // "Description" and "Examples" H2 sections in  mdString (if present).
-func applyDescriptionAndExamples(cmd *cobra.Command, mdString string) {
+func ApplyDescriptionAndExamples(cmd *cobra.Command, mdString string) {
 	sections := getSections(mdString)
 	var (
 		anchors []string

yamldocs_test.go

@@ -0,0 +1,28 @@
+package yamldocs
+
+import (
+	"io/ioutil"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+func TestGenYamlTree(t *testing.T) {
+	c := &cobra.Command{Use: "do [OPTIONS] arg1 arg2"}
+
+	tmpdir, err := ioutil.TempDir("", "test-gen-yaml-tree")
+	if err != nil {
+		t.Fatalf("Failed to create tmpdir: %s", err.Error())
+	}
+	defer os.RemoveAll(tmpdir)
+
+	if err := GenYamlTree(c, tmpdir); err != nil {
+		t.Fatalf("GenYamlTree failed: %s", err.Error())
+	}
+
+	if _, err := os.Stat(filepath.Join(tmpdir, "do.yaml")); err != nil {
+		t.Fatalf("Expected file 'do.yaml' to exist")
+	}
+}