From e615d4a5e161378078ecc98662ae3941a7e3e225 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 10 Feb 2026 19:42:50 +0100 Subject: [PATCH 1/2] yaml: add "generated file" header Signed-off-by: Sebastiaan van Stijn --- clidocstool.go | 3 +++ clidocstool_yaml.go | 5 +++-- fixtures/docker.yaml | 1 + fixtures/docker_attach.yaml | 1 + fixtures/docker_buildx.yaml | 1 + fixtures/docker_buildx_build.yaml | 1 + fixtures/docker_buildx_dial-stdio.yaml | 1 + fixtures/docker_buildx_imagetools.yaml | 1 + fixtures/docker_buildx_imagetools_create.yaml | 1 + fixtures/docker_buildx_install.yaml | 1 + fixtures/docker_buildx_stop.yaml | 1 + 11 files changed, 15 insertions(+), 2 deletions(-) diff --git a/clidocstool.go b/clidocstool.go index cee6dbe..6b853ca 100644 --- a/clidocstool.go +++ b/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 diff --git a/clidocstool_yaml.go b/clidocstool_yaml.go index e55e5ad..31a9d5c 100644 --- a/clidocstool_yaml.go +++ b/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. diff --git a/fixtures/docker.yaml b/fixtures/docker.yaml index 9dcc8b2..74449d8 100644 --- a/fixtures/docker.yaml +++ b/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 diff --git a/fixtures/docker_attach.yaml b/fixtures/docker_attach.yaml index 1b109d5..da65eae 100644 --- a/fixtures/docker_attach.yaml +++ b/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: | diff --git a/fixtures/docker_buildx.yaml b/fixtures/docker_buildx.yaml index a7c7f4b..1b866f8 100644 --- a/fixtures/docker_buildx.yaml +++ b/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 diff --git a/fixtures/docker_buildx_build.yaml b/fixtures/docker_buildx_build.yaml index 510dbae..b526211 100644 --- a/fixtures/docker_buildx_build.yaml +++ b/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 diff --git a/fixtures/docker_buildx_dial-stdio.yaml b/fixtures/docker_buildx_dial-stdio.yaml index 3e6f3eb..6966843 100644 --- a/fixtures/docker_buildx_dial-stdio.yaml +++ b/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 diff --git a/fixtures/docker_buildx_imagetools.yaml b/fixtures/docker_buildx_imagetools.yaml index ff58c4b..39ad866 100644 --- a/fixtures/docker_buildx_imagetools.yaml +++ b/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 diff --git a/fixtures/docker_buildx_imagetools_create.yaml b/fixtures/docker_buildx_imagetools_create.yaml index 146b299..6a0d601 100644 --- a/fixtures/docker_buildx_imagetools_create.yaml +++ b/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 diff --git a/fixtures/docker_buildx_install.yaml b/fixtures/docker_buildx_install.yaml index 5389e01..2d59e8f 100644 --- a/fixtures/docker_buildx_install.yaml +++ b/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 diff --git a/fixtures/docker_buildx_stop.yaml b/fixtures/docker_buildx_stop.yaml index f94dee2..5262c98 100644 --- a/fixtures/docker_buildx_stop.yaml +++ b/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 From 8fa1c1a4018e60238fd1776f57a5600b7c99ac3a Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 10 Feb 2026 20:14:30 +0100 Subject: [PATCH 2/2] man: prevent cobra "source" comment Cobra sets a default Source if none is set; header.Source = "Auto generated by spf13/cobra" Set our own Source for the man pages we generate. Signed-off-by: Sebastiaan van Stijn --- clidocstool_man.go | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/clidocstool_man.go b/clidocstool_man.go index 1b085f1..fa7af85 100644 --- a/clidocstool_man.go +++ b/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)