reStructuredText supports commands with slashes

doc/md_docs.go

@@ -20,20 +20,11 @@ import (
 	"os"
 	"path/filepath"
 	"sort"
-	"strings"
 	"time"
 
 	"github.com/spf13/cobra"
 )
 
-func cleanCommandName(name string) string {
-	r := strings.NewReplacer(
-		" ", "_",
-		"/", "_",
-	)
-	return r.Replace(name)
-}
-
 func printOptions(buf *bytes.Buffer, cmd *cobra.Command, name string) error {
 	flags := cmd.NonInheritedFlags()
 	flags.SetOutput(buf)

doc/rest_docs.go

@@ -70,7 +70,7 @@ func GenReSTCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string, str
 	if len(long) == 0 {
 		long = short
 	}
-	ref := strings.ReplaceAll(name, " ", "_")
+	ref := cleanCommandName(name)
 
 	buf.WriteString(".. _" + ref + ":\n\n")
 	buf.WriteString(name + "\n")
@@ -99,7 +99,7 @@ func GenReSTCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string, str
 		if cmd.HasParent() {
 			parent := cmd.Parent()
 			pname := parent.CommandPath()
-			ref = strings.ReplaceAll(pname, " ", "_")
+			ref = cleanCommandName(pname)
 			buf.WriteString(fmt.Sprintf("* %s \t - %s\n", linkHandler(pname, ref), parent.Short))
 			cmd.VisitParents(func(c *cobra.Command) {
 				if c.DisableAutoGenTag {
@@ -116,7 +116,7 @@ func GenReSTCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string, str
 				continue
 			}
 			cname := name + " " + child.Name()
-			ref = strings.ReplaceAll(cname, " ", "_")
+			ref = cleanCommandName(cname)
 			buf.WriteString(fmt.Sprintf("* %s \t - %s\n", linkHandler(cname, ref), child.Short))
 		}
 		buf.WriteString("\n")
@@ -151,7 +151,7 @@ func GenReSTTreeCustom(cmd *cobra.Command, dir string, filePrepender func(string
 		}
 	}
 
-	basename := strings.ReplaceAll(cmd.CommandPath(), " ", "_") + ".rst"
+	basename := cleanCommandName(cmd.CommandPath()) + ".rst"
 	filename := filepath.Join(dir, basename)
 	f, err := os.Create(filename)
 	if err != nil {

doc/rest_docs_test.go

@@ -82,6 +82,24 @@ func TestGenRSTTree(t *testing.T) {
 	}
 }
 
+func TestGenRSTTreeSlashCommands(t *testing.T) {
+	c := &cobra.Command{Use: "run/first [OPTIONS] arg1 arg2"}
+
+	tmpdir, err := ioutil.TempDir("", "test-gen-rst-tree-slash-commands")
+	if err != nil {
+		t.Fatalf("Failed to create tmpdir: %s", err.Error())
+	}
+	defer os.RemoveAll(tmpdir)
+
+	if err := GenReSTTree(c, tmpdir); err != nil {
+		t.Fatalf("GenReSTTree failed: %s", err.Error())
+	}
+
+	if _, err := os.Stat(filepath.Join(tmpdir, "run_first.rst")); err != nil {
+		t.Fatalf("Expected file 'run_first.rst' to exist")
+	}
+}
+
 func BenchmarkGenReSTToFile(b *testing.B) {
 	file, err := ioutil.TempFile("", "")
 	if err != nil {

doc/util.go

@@ -19,6 +19,16 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// cleanCommandName removes problematic characters from a command's name
+// This allows generating commands such as 'perform run/first'.
+func cleanCommandName(name string) string {
+	r := strings.NewReplacer(
+		" ", "_",
+		"/", "_",
+	)
+	return r.Replace(name)
+}
+
 // Test to see if we have a reason to print See Also information in docs
 // Basically this is a test for a parent command or a subcommand which is
 // both not deprecated and not the autogenerated help command.