feat/docgen: generate docs for legacy and urfave commands

Author: burmudar

cmd/src/doc.go

@@ -7,11 +7,14 @@ import (
 	"io"
 	"os"
 	"path"
+	"sort"
 	"strings"
 	"text/template"
 
+	"github.com/sourcegraph/sourcegraph/lib/docgen"
 	"github.com/sourcegraph/sourcegraph/lib/errors"
 	"github.com/sourcegraph/sourcegraph/lib/output"
+	"github.com/urfave/cli/v3"
 
 	"github.com/sourcegraph/src-cli/internal/cmderrors"
 )
@@ -29,7 +32,7 @@ documentation used within Sourcegraph.
 Usage:
 
 	src doc -o DIR
-	
+
 Examples:
 
     $ src doc -o ~/sourcegraph/doc/integration/cli/reference
@@ -47,6 +50,8 @@ Examples:
 			return cmderrors.ExitCode(1, nil)
 		}
 
+		dstDir := *outputFlag
+
 		dr, err := newDocRenderer()
 		if err != nil {
 			return err
@@ -66,6 +71,7 @@ Examples:
 
 		pending := out.Pending(output.Line("", output.StylePending, "Rendering Markdown..."))
 		count := 0
+		rootSubcommands := map[string]string{}
 		defer func() {
 			pending.Complete(output.Linef(output.EmojiSuccess, output.StyleSuccess, "%d files rendered under %s", count, *outputFlag))
 		}()
@@ -94,7 +100,7 @@ Examples:
 						return err
 					}
 
-					file, err := openDocFile(*outputFlag, fqcn)
+					file, err := openDocFile(dstDir, fqcn)
 					if err != nil {
 						return err
 					}
@@ -110,12 +116,19 @@ Examples:
 				}
 			}
 
+			if groupName == "" {
+				for name, link := range subcommands {
+					rootSubcommands[name] = link
+				}
+				continue
+			}
+
 			content, err := dr.RenderGroup(groupName, subcommands)
 			if err != nil {
 				return err
 			}
 
-			file, err := openDocFile(*outputFlag, groupName+" index")
+			file, err := openDocFile(dstDir, groupName+" index")
 			if err != nil {
 				return err
 			}
@@ -127,6 +140,44 @@ Examples:
 			count++
 		}
 
+		root := migratedRootCommand()
+		mdFiles, err := docgen.Markdown(root)
+		if err != nil {
+			return err
+		}
+
+		for _, cmd := range migratedVisibleCommands(root.Commands) {
+			rootSubcommands[cmd.Name] = migratedDocLink(cmd)
+		}
+
+		for _, md := range mdFiles {
+			pending.Update(md.Name)
+			docPath := path.Join(dstDir, md.Name)
+			if err := os.MkdirAll(path.Dir(docPath), 0755); err != nil {
+				return err
+			}
+			if err := os.WriteFile(docPath, []byte(md.Content), 0644); err != nil {
+				return err
+			}
+			count++
+		}
+
+		content, err := dr.RenderGroup("", rootSubcommands)
+		if err != nil {
+			return err
+		}
+
+		file, err := openDocFile(dstDir, " index")
+		if err != nil {
+			return err
+		}
+		defer file.Close()
+
+		if _, err := file.WriteString(content); err != nil {
+			return err
+		}
+		count++
+
 		return nil
 	}
 
@@ -151,6 +202,29 @@ func openDocFile(base, fqcn string) (interface {
 	return os.Create(cmdPath + ".md")
 }
 
+func migratedVisibleCommands(commands []*cli.Command) []*cli.Command {
+	visible := make([]*cli.Command, 0, len(commands))
+	for _, cmd := range commands {
+		if cmd.Hidden {
+			continue
+		}
+		visible = append(visible, cmd)
+	}
+
+	sort.Slice(visible, func(i, j int) bool {
+		return visible[i].Name < visible[j].Name
+	})
+
+	return visible
+}
+
+func migratedDocLink(cmd *cli.Command) string {
+	if len(migratedVisibleCommands(cmd.Commands)) > 0 {
+		return path.Join(cmd.Name, "index.md")
+	}
+	return cmd.Name + ".md"
+}
+
 type docRenderer struct {
 	commandTemplate *template.Template
 	groupTemplate   *template.Template