Skip to content

markdown: annotation to disable docs generation for flag and command#37

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
crazy-max wants to merge 1 commit into from
Closed

markdown: annotation to disable docs generation for flag and command #37

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions annotation/annotation.go
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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"
)
9 changes: 9 additions & 0 deletions clidocstool_md.go
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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)
Expand DownExpand Up@@ -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")
Expand All@@ -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 != "" {
Expand Down
1 change: 1 addition & 0 deletions clidocstool_md_test.go
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
10 changes: 10 additions & 0 deletions clidocstool_test.go
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -31,6 +31,7 @@ var (
buildxCmd *cobra.Command
buildxBuildCmd *cobra.Command
buildxStopCmd *cobra.Command
buildxServeCmd *cobra.Command
)

//nolint:errcheck
Expand DownExpand Up@@ -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")
Expand DownExpand Up@@ -174,6 +183,7 @@ format: "default|<id>[=<socket>|<key>[,<key>]]"`)

buildxCmd.AddCommand(buildxBuildCmd)
buildxCmd.AddCommand(buildxStopCmd)
buildxCmd.AddCommand(buildxServeCmd)
dockerCmd.AddCommand(buildxCmd)
}

Expand Down