Merge pull request #53 from dvdksn/fix-root-command-desc-examples

fix: generate long desc and examples for root command

clidocstool.go

@@ -88,33 +88,33 @@ func (c *Client) GenAllTree() error {
 }
 
 // loadLongDescription gets long descriptions and examples from markdown.
-func (c *Client) loadLongDescription(parentCmd *cobra.Command, generator string) error {
-	for _, cmd := range parentCmd.Commands() {
-		if cmd.HasSubCommands() {
-			if err := c.loadLongDescription(cmd, generator); err != nil {
+func (c *Client) loadLongDescription(cmd *cobra.Command, generator string) error {
+	if cmd.HasSubCommands() {
+		for _, sub := range cmd.Commands() {
+			if err := c.loadLongDescription(sub, generator); err != nil {
 				return err
 			}
 		}
-		name := cmd.CommandPath()
-		if i := strings.Index(name, " "); i >= 0 {
-			// remove root command / binary name
-			name = name[i+1:]
-		}
-		if name == "" {
-			continue
-		}
-		mdFile := strings.ReplaceAll(name, " ", "_") + ".md"
-		sourcePath := filepath.Join(c.source, mdFile)
-		content, err := os.ReadFile(sourcePath)
-		if os.IsNotExist(err) {
-			log.Printf("WARN: %s does not exist, skipping Markdown examples for %s docs\n", mdFile, generator)
-			continue
-		}
-		if err != nil {
-			return err
-		}
-		applyDescriptionAndExamples(cmd, string(content))
 	}
+	name := cmd.CommandPath()
+	if i := strings.Index(name, " "); i >= 0 {
+		// remove root command / binary name
+		name = name[i+1:]
+	}
+	if name == "" {
+		return nil
+	}
+	mdFile := strings.ReplaceAll(name, " ", "_") + ".md"
+	sourcePath := filepath.Join(c.source, mdFile)
+	content, err := os.ReadFile(sourcePath)
+	if os.IsNotExist(err) {
+		log.Printf("WARN: %s does not exist, skipping Markdown examples for %s docs\n", mdFile, generator)
+		return nil
+	}
+	if err != nil {
+		return err
+	}
+	applyDescriptionAndExamples(cmd, string(content))
 	return nil
 }
 

clidocstool_man_test.go

@@ -43,7 +43,7 @@ func TestGenManTree(t *testing.T) {
 	c, err := New(Options{
 		Root:      dockerCmd,
 		SourceDir: tmpdir,
-		Plugin:    true,
+		Plugin:    false,
 		ManHeader: &doc.GenManHeader{
 			Title:   "DOCKER",
 			Section: "1",

clidocstool_md_test.go

@@ -35,7 +35,7 @@ func TestGenMarkdownTree(t *testing.T) {
 	c, err := New(Options{
 		Root:      dockerCmd,
 		SourceDir: tmpdir,
-		Plugin:    true,
+		Plugin:    false,
 	})
 	require.NoError(t, err)
 	require.NoError(t, c.GenMarkdownTree(dockerCmd))

clidocstool_test.go

@@ -54,6 +54,11 @@ func setup() {
 		DisableFlagsInUseLine: true,
 	}
 
+	dockerCmd.PersistentFlags().BoolP("help", "h", false, "Print usage")
+	dockerCmd.PersistentFlags().MarkShorthandDeprecated("help", "please use --help")
+	dockerCmd.PersistentFlags().Lookup("help").Hidden = true
+	dockerCmd.Flags().StringP("host", "H", "unix:///var/run/docker.sock", "Daemon socket to connect to")
+
 	attachCmd = &cobra.Command{
 		Use:   "attach [OPTIONS] CONTAINER",
 		Short: "Attach local standard input, output, and error streams to a running container",
@@ -237,7 +242,7 @@ func TestGenAllTree(t *testing.T) {
 	c, err := New(Options{
 		Root:      dockerCmd,
 		SourceDir: tmpdir,
-		Plugin:    true,
+		Plugin:    false,
 		ManHeader: &doc.GenManHeader{
 			Title:   "DOCKER",
 			Section: "1",

clidocstool_yaml_test.go

@@ -33,7 +33,7 @@ func TestGenYamlTree(t *testing.T) {
 	c, err := New(Options{
 		Root:      dockerCmd,
 		SourceDir: tmpdir,
-		Plugin:    true,
+		Plugin:    false,
 	})
 	require.NoError(t, err)
 	require.NoError(t, c.GenYamlTree(dockerCmd))

fixtures/docker-attach.1

@@ -21,10 +21,6 @@ Attach local standard input, output, and error streams to a running container
 \fB--detach-keys\fP=""
 	Override the key sequence for detaching a container
 
-.PP
-\fB-h\fP, \fB--help\fP[=false]
-	help for attach
-
 .PP
 \fB--no-stdin\fP[=false]
 	Do not attach STDIN

fixtures/docker-buildx-build.1

@@ -49,10 +49,6 @@ Start a build
 \fB-f\fP, \fB--file\fP=""
 	Name of the Dockerfile (default: "PATH/Dockerfile")
 
-.PP
-\fB-h\fP, \fB--help\fP[=false]
-	help for build
-
 .PP
 \fB--iidfile\fP=""
 	Write the image ID to the file

fixtures/docker-buildx-dial-stdio.1

@@ -17,10 +17,6 @@ Proxy current stdio streams to builder instance
 
 
 .SH OPTIONS
-.PP
-\fB-h\fP, \fB--help\fP[=false]
-	help for dial-stdio
-
 .PP
 \fB--platform\fP=""
 	Target platform: this is used for node selection

fixtures/docker-buildx-install.1

@@ -16,12 +16,6 @@ docker-buildx-install - Install buildx as a 'docker builder' alias
 Install buildx as a 'docker builder' alias
 
 
-.SH OPTIONS
-.PP
-\fB-h\fP, \fB--help\fP[=false]
-	help for install
-
-
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB--builder\fP=""

fixtures/docker-buildx-stop.1

@@ -16,12 +16,6 @@ docker-buildx-stop - Stop builder instance
 Stop builder instance
 
 
-.SH OPTIONS
-.PP
-\fB-h\fP, \fB--help\fP[=false]
-	help for stop
-
-
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB--builder\fP=""

fixtures/docker-buildx.1

@@ -21,10 +21,6 @@ Extended build capabilities with BuildKit
 \fB--builder\fP=""
 	Override the configured builder instance
 
-.PP
-\fB-h\fP, \fB--help\fP[=false]
-	help for buildx
-
 
 .SH SEE ALSO
 .PP

fixtures/docker.1

@@ -0,0 +1,27 @@
+.nh
+.TH "DOCKER" "1" "Jan 2020" "Docker Community" "Docker User Manuals"
+
+.SH NAME
+.PP
+docker - A self-sufficient runtime for containers
+
+
+.SH SYNOPSIS
+.PP
+\fBdocker [OPTIONS] COMMAND [ARG...]\fP
+
+
+.SH DESCRIPTION
+.PP
+A self-sufficient runtime for containers
+
+
+.SH OPTIONS
+.PP
+\fB-H\fP, \fB--host\fP="unix:///var/run/docker.sock"
+	Daemon socket to connect to
+
+
+.SH SEE ALSO
+.PP
+\fBdocker-attach(1)\fP, \fBdocker-buildx(1)\fP

fixtures/docker.md

@@ -0,0 +1,22 @@
+# docker
+
+<!---MARKER_GEN_START-->
+A self-sufficient runtime for containers
+
+### Subcommands
+
+| Name                  | Description                                                                   |
+|:----------------------|:------------------------------------------------------------------------------|
+| [`attach`](attach.md) | Attach local standard input, output, and error streams to a running container |
+| [`buildx`](buildx.md) | Docker Buildx                                                                 |
+
+
+### Options
+
+| Name           | Type     | Default                       | Description                 |
+|:---------------|:---------|:------------------------------|:----------------------------|
+| `-H`, `--host` | `string` | `unix:///var/run/docker.sock` | Daemon socket to connect to |
+
+
+<!---MARKER_GEN_END-->
+

fixtures/docker.yaml

@@ -0,0 +1,39 @@
+command: docker
+short: A self-sufficient runtime for containers
+long: A self-sufficient runtime for containers
+usage: docker [OPTIONS] COMMAND [ARG...]
+cname:
+    - docker attach
+    - docker buildx
+clink:
+    - docker_attach.yaml
+    - docker_buildx.yaml
+options:
+    - option: help
+      value_type: bool
+      default_value: "false"
+      description: Print usage
+      deprecated: false
+      hidden: true
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: host
+      shorthand: H
+      value_type: string
+      default_value: unix:///var/run/docker.sock
+      description: Daemon socket to connect to
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+deprecated: false
+hidden: false
+experimental: false
+experimentalcli: false
+kubernetes: false
+swarm: false
+

fixtures/docker_attach.yaml

@@ -37,6 +37,17 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: help
+      value_type: bool
+      default_value: "false"
+      description: Print usage
+      deprecated: false
+      hidden: true
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
 hidden: false
 experimental: false

fixtures/docker_buildx.yaml

@@ -21,6 +21,17 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+inherited_options:
+    - option: help
+      value_type: bool
+      default_value: "false"
+      description: Print usage
+      deprecated: false
+      hidden: true
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
 hidden: false
 experimental: false

fixtures/docker_buildx_build.yaml

@@ -374,6 +374,16 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: help
+      value_type: bool
+      default_value: "false"
+      description: Print usage
+      deprecated: false
+      hidden: true
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
 hidden: false
 experimental: false

fixtures/docker_buildx_dial-stdio.yaml

@@ -34,6 +34,16 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: help
+      value_type: bool
+      default_value: "false"
+      description: Print usage
+      deprecated: false
+      hidden: true
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
 hidden: false
 experimental: false

fixtures/docker_buildx_install.yaml

@@ -14,6 +14,16 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: help
+      value_type: bool
+      default_value: "false"
+      description: Print usage
+      deprecated: false
+      hidden: true
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
 hidden: true
 experimental: false

fixtures/docker_buildx_stop.yaml

@@ -14,6 +14,16 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: help
+      value_type: bool
+      default_value: "false"
+      description: Print usage
+      deprecated: false
+      hidden: true
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
 deprecated: false
 hidden: false
 experimental: false