markdown: annotation to disable docs generation for flag and command

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"
 )

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 != "" {

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

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)
 }