From 55063ff4c28914afb5cd2b679848f43da016be9a Mon Sep 17 00:00:00 2001
From: CrazyMax <crazy-max@users.noreply.github.com>
Date: Tue, 20 Jun 2023 00:34:32 +0200
Subject: [PATCH] markdown: annotation to disable docs generation for flag and
 command

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>
---
 annotation/annotation.go |  3 +++
 clidocstool_md.go        |  9 +++++++++
 clidocstool_md_test.go   |  1 +
 clidocstool_test.go      | 10 ++++++++++
 4 files changed, 23 insertions(+)

diff --git a/annotation/annotation.go b/annotation/annotation.go
index 021846a..7dbc6f1 100644
--- a/annotation/annotation.go
+++ b/annotation/annotation.go
@@ -22,4 +22,7 @@ const (
 	CodeDelimiter = "docs.code-delimiter"
 	// DefaultValue specifies the default value for a flag.
 	DefaultValue = "docs.default-value"
+	// MardownNoGen specifies that the command or flag mparkdown docs should
+	// not be generated.
+	MardownNoGen = "docs.markdown-no-gen"
 )
diff --git a/clidocstool_md.go b/clidocstool_md.go
index 73d05c8..68dc20c 100644
--- a/clidocstool_md.go
+++ b/clidocstool_md.go
@@ -52,6 +52,9 @@ func (c *Client) GenMarkdownTree(cmd *cobra.Command) error {
 	if c.plugin && !cmd.HasParent() {
 		return nil
 	}
+	if _, ok := cmd.Annotations[annotation.MardownNoGen]; ok {
+		return nil
+	}
 
 	log.Printf("INFO: Generating Markdown for %q", cmd.CommandPath())
 	mdFile := mdFilename(cmd)
@@ -208,6 +211,9 @@ func mdCmdOutput(cmd *cobra.Command, old string) (string, error) {
 		b.WriteString("### Subcommands\n\n")
 		table := newMdTable("Name", "Description")
 		for _, c := range cmd.Commands() {
+			if _, ok := c.Annotations[annotation.MardownNoGen]; ok {
+				continue
+			}
 			table.AddRow(fmt.Sprintf("[`%s`](%s)", c.Name(), mdFilename(c)), c.Short)
 		}
 		b.WriteString(table.String() + "\n")
@@ -223,6 +229,9 @@ func mdCmdOutput(cmd *cobra.Command, old string) (string, error) {
 			if f.Hidden {
 				return
 			}
+			if _, ok := f.Annotations[annotation.MardownNoGen]; ok {
+				return
+			}
 			isLink := strings.Contains(old, "<a name=\""+f.Name+"\"></a>")
 			var name string
 			if f.Shorthand != "" {
diff --git a/clidocstool_md_test.go b/clidocstool_md_test.go
index ec2c970..91fec2e 100644
--- a/clidocstool_md_test.go
+++ b/clidocstool_md_test.go
@@ -38,6 +38,7 @@ func TestGenMarkdownTree(t *testing.T) {
 	})
 	require.NoError(t, err)
 	require.NoError(t, c.GenMarkdownTree(buildxCmd))
+	require.NoFileExists(t, filepath.Join(tmpdir, "buildx__INTERNAL_SERVE.md"))
 
 	for _, tt := range []string{"buildx.md", "buildx_build.md", "buildx_stop.md"} {
 		tt := tt
diff --git a/clidocstool_test.go b/clidocstool_test.go
index 141bdd6..e6f054d 100644
--- a/clidocstool_test.go
+++ b/clidocstool_test.go
@@ -31,6 +31,7 @@ var (
 	buildxCmd      *cobra.Command
 	buildxBuildCmd *cobra.Command
 	buildxStopCmd  *cobra.Command
+	buildxServeCmd *cobra.Command
 )
 
 //nolint:errcheck
@@ -67,6 +68,14 @@ func init() {
 		Short: "Stop builder instance",
 		Run:   func(cmd *cobra.Command, args []string) {},
 	}
+	buildxServeCmd = &cobra.Command{
+		Use:    "_INTERNAL_SERVE [OPTIONS]",
+		Hidden: true,
+		Run:    func(cmd *cobra.Command, args []string) {},
+		Annotations: map[string]string{
+			annotation.MardownNoGen: "",
+		},
+	}
 
 	buildxPFlags := buildxCmd.PersistentFlags()
 	buildxPFlags.String("builder", os.Getenv("BUILDX_BUILDER"), "Override the configured builder instance")
@@ -174,6 +183,7 @@ format: "default|<id>[=<socket>|<key>[,<key>]]"`)
 
 	buildxCmd.AddCommand(buildxBuildCmd)
 	buildxCmd.AddCommand(buildxStopCmd)
+	buildxCmd.AddCommand(buildxServeCmd)
 	dockerCmd.AddCommand(buildxCmd)
 }