YAML: add "generated file" comment, and set custom default "source" for man pages

clidocstool.go

@@ -27,6 +27,9 @@ import (
 	"github.com/spf13/cobra/doc"
 )
 
+// generatedFile is the text to add as comment on generated files.
+const generatedFile = `Code generated by github.com/docker/cli-docs-tool; DO NOT EDIT.`
+
 // Options defines options for cli-docs-tool
 type Options struct {
 	Root      *cobra.Command

clidocstool_man.go

@@ -33,13 +33,18 @@ func (c *Client) GenManTree(cmd *cobra.Command) error {
 		return err
 	}
 
-	if epoch := os.Getenv("SOURCE_DATE_EPOCH"); c.manHeader != nil && epoch != "" {
-		unixEpoch, err := strconv.ParseInt(epoch, 10, 64)
-		if err != nil {
-			return fmt.Errorf("invalid SOURCE_DATE_EPOCH: %v", err)
+	if c.manHeader != nil {
+		if epoch := os.Getenv("SOURCE_DATE_EPOCH"); epoch != "" {
+			unixEpoch, err := strconv.ParseInt(epoch, 10, 64)
+			if err != nil {
+				return fmt.Errorf("invalid SOURCE_DATE_EPOCH: %v", err)
+			}
+			now := time.Unix(unixEpoch, 0)
+			c.manHeader.Date = &now
+		}
+		if c.manHeader.Source == "" {
+			c.manHeader.Source = "Generated by github.com/docker/cli-docs-tool"
 		}
-		now := time.Unix(unixEpoch, 0)
-		c.manHeader.Date = &now
 	}
 
 	return c.genManTreeCustom(cmd)

clidocstool_yaml.go

@@ -77,11 +77,12 @@ type cmdDoc struct {
 // 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 (c *Client) GenYamlTree(cmd *cobra.Command) error {
-	emptyStr := func(string) string { return "" }
 	if err := c.loadLongDescription(cmd, "yaml"); err != nil {
 		return err
 	}
-	return c.genYamlTreeCustom(cmd, emptyStr)
+	return c.genYamlTreeCustom(cmd, func(string) string {
+		return "# " + generatedFile + "\n"
+	})
 }
 
 // genYamlTreeCustom creates yaml structured ref files.

fixtures/docker.yaml

@@ -1,3 +1,4 @@
+# Code generated by github.com/docker/cli-docs-tool; DO NOT EDIT.
 command: docker
 short: A self-sufficient runtime for containers
 long: A self-sufficient runtime for containers

fixtures/docker_attach.yaml

@@ -1,3 +1,4 @@
+# Code generated by github.com/docker/cli-docs-tool; DO NOT EDIT.
 command: docker attach
 aliases: docker container attach, docker attach
 short: |

fixtures/docker_buildx.yaml

@@ -1,3 +1,4 @@
+# Code generated by github.com/docker/cli-docs-tool; DO NOT EDIT.
 command: docker buildx
 short: Docker Buildx
 long: Extended build capabilities with BuildKit

fixtures/docker_buildx_build.yaml

@@ -1,3 +1,4 @@
+# Code generated by github.com/docker/cli-docs-tool; DO NOT EDIT.
 command: docker buildx build
 aliases: docker image build, docker buildx build, docker buildx b, docker build
 short: Start a build

fixtures/docker_buildx_dial-stdio.yaml

@@ -1,3 +1,4 @@
+# Code generated by github.com/docker/cli-docs-tool; DO NOT EDIT.
 command: docker buildx dial-stdio
 short: Proxy current stdio streams to builder instance
 long: Proxy current stdio streams to builder instance

fixtures/docker_buildx_imagetools.yaml

@@ -1,3 +1,4 @@
+# Code generated by github.com/docker/cli-docs-tool; DO NOT EDIT.
 command: docker buildx imagetools
 short: Commands to work on images in registry
 long: Commands to work on images in registry

fixtures/docker_buildx_imagetools_create.yaml

@@ -1,3 +1,4 @@
+# Code generated by github.com/docker/cli-docs-tool; DO NOT EDIT.
 command: docker buildx imagetools create
 short: Create a new image based on source images
 long: Create a new image based on source images

fixtures/docker_buildx_install.yaml

@@ -1,3 +1,4 @@
+# Code generated by github.com/docker/cli-docs-tool; DO NOT EDIT.
 command: docker buildx install
 short: Install buildx as a 'docker builder' alias
 long: Install buildx as a 'docker builder' alias

fixtures/docker_buildx_stop.yaml

@@ -1,3 +1,4 @@
+# Code generated by github.com/docker/cli-docs-tool; DO NOT EDIT.
 command: docker buildx stop
 short: Stop builder instance
 long: Stop builder instance