feat: support subdirectory splitting for grouped command docs

Add a `-group` flag to gen-docs that specifies command names whose
subcommands should each get their own file in a subdirectory rather than
all being combined into a single file. This is needed for the cloud CLI
extension, which has ~130 commands that would produce an unmanageably
large single page.

Usage:

  go run ./cmd/gen-docs \
    -input internal/temporalcli/commands.yaml \
    -input path/to/cloud-cli/commands.yml \
    -group cloud \
    -output dist/docs

This produces cloud/namespace.mdx, cloud/user.mdx, cloud/apikey.mdx,
etc. alongside the existing flat files. Existing non-grouped commands
are unaffected.

Also fixes the encodeJSONExample regex to catch standalone JSON objects
in single quotes (e.g., '{"key":"value"}'), not just key=value patterns.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: lennessyy

cmd/gen-docs/main.go

@@ -10,7 +10,7 @@ import (
 	"github.com/temporalio/cli/internal/commandsgen"
 )
 
-// stringSlice implements flag.Value to support multiple -input flags
+// stringSlice implements flag.Value to support multiple flags of the same name
 type stringSlice []string
 
 func (s *stringSlice) String() string {
@@ -30,12 +30,14 @@ func main() {
 
 func run() error {
 	var (
-		outputDir  string
-		inputFiles stringSlice
+		outputDir    string
+		inputFiles   stringSlice
+		groupedNames stringSlice
 	)
 
 	flag.Var(&inputFiles, "input", "Input YAML file (can be specified multiple times)")
 	flag.StringVar(&outputDir, "output", ".", "Output directory for docs")
+	flag.Var(&groupedNames, "group", "Command name whose subcommands get separate files in a subdirectory (can be specified multiple times)")
 	flag.Parse()
 
 	if len(inputFiles) == 0 {
@@ -60,13 +62,19 @@ func run() error {
 		return fmt.Errorf("failed parsing YAML: %w", err)
 	}
 
-	docs, err := commandsgen.GenerateDocsFiles(cmds)
+	docs, err := commandsgen.GenerateDocsFiles(cmds, groupedNames)
 	if err != nil {
 		return fmt.Errorf("failed generating docs: %w", err)
 	}
 
 	for filename, content := range docs {
 		filePath := filepath.Join(outputDir, filename+".mdx")
+		// Create subdirectories if the filename contains a path separator (e.g., "cloud/namespace")
+		if dir := filepath.Dir(filePath); dir != "" {
+			if err := os.MkdirAll(dir, 0755); err != nil {
+				return fmt.Errorf("failed creating directory %s: %w", dir, err)
+			}
+		}
 		if err := os.WriteFile(filePath, content, 0644); err != nil {
 			return fmt.Errorf("failed writing %s: %w", filePath, err)
 		}

internal/commandsgen/docs.go

@@ -8,17 +8,27 @@ import (
 	"strings"
 )
 
-func GenerateDocsFiles(commands Commands) (map[string][]byte, error) {
+// GenerateDocsFiles generates documentation files from parsed commands.
+// groupedNames specifies command names whose subcommands should each get their
+// own file in a subdirectory (e.g., passing "cloud" produces cloud/namespace.mdx,
+// cloud/user.mdx, etc. instead of a single cloud.mdx).
+func GenerateDocsFiles(commands Commands, groupedNames []string) (map[string][]byte, error) {
 	optionSetMap := make(map[string]OptionSets)
 	for i, optionSet := range commands.OptionSets {
 		optionSetMap[optionSet.Name] = commands.OptionSets[i]
 	}
 
+	groupedParents := make(map[string]bool)
+	for _, name := range groupedNames {
+		groupedParents[name] = true
+	}
+
 	w := &docWriter{
 		fileMap:        make(map[string]*bytes.Buffer),
 		optionSetMap:   optionSetMap,
 		allCommands:    commands.CommandList,
 		globalFlagsMap: make(map[string]map[string]Option),
+		groupedParents: groupedParents,
 	}
 
 	// sorted ascending by full name of command (activity complete, batch list, etc)
@@ -45,13 +55,34 @@ type docWriter struct {
 	optionSetMap   map[string]OptionSets
 	optionsStack   [][]Option
 	globalFlagsMap map[string]map[string]Option // fileName -> optionName -> Option
+	groupedParents map[string]bool              // depth-1 command names that use subdirectory splitting
 }
 
 func (c *Command) writeDoc(w *docWriter) error {
 	w.processOptions(c)
 
-	// If this is a root command, write a new file
 	depth := c.depth()
+
+	// Check if this command itself is the grouped root, or belongs to one.
+	// A grouped root command (e.g., "cloud") is skipped - it has no standalone file.
+	// Its direct children (e.g., "cloud namespace") each get their own file in a subdirectory.
+	if w.groupedParents[c.FullName] {
+		// This is the grouped root - skip it
+		return nil
+	}
+	if depth >= 1 {
+		// Walk up the tree to find if any ancestor is a grouped parent
+		parts := strings.Split(c.FullName, " ")
+		for i := len(parts) - 1; i >= 1; i-- {
+			ancestor := strings.Join(parts[:i], " ")
+			if w.groupedParents[ancestor] {
+				c.writeGroupedDoc(w, ancestor)
+				return nil
+			}
+		}
+	}
+
+	// Standard (non-grouped) handling
 	if depth == 1 {
 		w.writeCommand(c)
 	} else if depth > 1 {
@@ -60,6 +91,22 @@ func (c *Command) writeDoc(w *docWriter) error {
 	return nil
 }
 
+func (c *Command) writeGroupedDoc(w *docWriter, groupRoot string) {
+	// How many parts does the group root have?
+	groupDepth := len(strings.Split(groupRoot, " "))
+	parts := strings.Split(c.FullName, " ")
+	relativeDepth := len(parts) - groupDepth
+
+	switch {
+	case relativeDepth == 1:
+		// Direct child of grouped root (e.g., "cloud namespace") - new file
+		w.writeGroupedCommand(c, groupRoot)
+	case relativeDepth > 1:
+		// Deeper subcommand (e.g., "cloud namespace get") - append to parent file
+		w.writeGroupedSubcommand(c, groupRoot)
+	}
+}
+
 func (w *docWriter) writeCommand(c *Command) {
 	fileName := c.fileName()
 	w.fileMap[fileName] = &bytes.Buffer{}
@@ -88,6 +135,107 @@ func (w *docWriter) writeCommand(c *Command) {
 	w.fileMap[fileName].WriteString("Refer to [Global Flags](#global-flags) for flags that you can use with every subcommand.\n\n")
 }
 
+// groupedFileName returns the file path for a command within a grouped parent.
+// For example, with groupRoot "cloud" and command "cloud namespace", returns "cloud/namespace".
+func groupedFileName(c *Command, groupRoot string) string {
+	groupParts := strings.Split(groupRoot, " ")
+	cmdParts := strings.Split(c.FullName, " ")
+	// The file is named after the first part after the group root
+	if len(cmdParts) <= len(groupParts) {
+		return ""
+	}
+	return strings.Join(groupParts, "-") + "/" + cmdParts[len(groupParts)]
+}
+
+func (w *docWriter) writeGroupedCommand(c *Command, groupRoot string) {
+	fileName := groupedFileName(c, groupRoot)
+	groupParts := strings.Split(groupRoot, " ")
+	cmdParts := strings.Split(c.FullName, " ")
+	leafName := cmdParts[len(groupParts)]
+	fullCmdName := strings.Join(cmdParts, " ")
+
+	w.fileMap[fileName] = &bytes.Buffer{}
+	w.fileMap[fileName].WriteString("---\n")
+	w.fileMap[fileName].WriteString("id: " + leafName + "\n")
+	w.fileMap[fileName].WriteString("title: Temporal CLI " + fullCmdName + " command reference\n")
+	w.fileMap[fileName].WriteString("sidebar_label: " + leafName + "\n")
+	w.fileMap[fileName].WriteString("description: " + c.Docs.DescriptionHeader + "\n")
+	w.fileMap[fileName].WriteString("toc_max_heading_level: 4\n")
+
+	w.fileMap[fileName].WriteString("keywords:\n")
+	for _, keyword := range c.Docs.Keywords {
+		w.fileMap[fileName].WriteString("  - " + keyword + "\n")
+	}
+	w.fileMap[fileName].WriteString("tags:\n")
+	for _, tag := range c.Docs.Tags {
+		w.fileMap[fileName].WriteString("  - " + tag + "\n")
+	}
+	w.fileMap[fileName].WriteString("---")
+	w.fileMap[fileName].WriteString("\n\n")
+	w.fileMap[fileName].WriteString("{/* NOTE: This is an auto-generated file. Any edit to this file will be overwritten.\n")
+	w.fileMap[fileName].WriteString("This file is generated from https://github.com/temporalio/cli via cmd/gen-docs */}\n\n")
+	w.fileMap[fileName].WriteString(fmt.Sprintf("This page provides a reference for the `temporal %s` commands. ", fullCmdName))
+	w.fileMap[fileName].WriteString("The flags applicable to each subcommand are presented in a table within the heading for the subcommand. ")
+	w.fileMap[fileName].WriteString("Refer to [Global Flags](#global-flags) for flags that you can use with every subcommand.\n\n")
+}
+
+func (w *docWriter) writeGroupedSubcommand(c *Command, groupRoot string) {
+	fileName := groupedFileName(c, groupRoot)
+	groupParts := strings.Split(groupRoot, " ")
+	cmdParts := strings.Split(c.FullName, " ")
+	// Heading depth is relative to the grouped file root
+	// e.g., "cloud namespace get" with groupRoot "cloud" → relativeDepth 2 → ## heading
+	relativeDepth := len(cmdParts) - len(groupParts)
+	prefix := strings.Repeat("#", relativeDepth)
+	leafParts := cmdParts[len(groupParts)+1:]
+	leafName := strings.Join(leafParts, "")
+
+	w.fileMap[fileName].WriteString(prefix + " " + leafName + "\n\n")
+	w.fileMap[fileName].WriteString(c.Description + "\n\n")
+
+	if w.isLeafCommand(c) {
+		var options = make([]Option, 0)
+		var globalOptions = make([]Option, 0)
+		for i, o := range w.optionsStack {
+			if i == len(w.optionsStack)-1 {
+				options = append(options, o...)
+			} else {
+				globalOptions = append(globalOptions, o...)
+			}
+		}
+
+		sort.Slice(options, func(i, j int) bool {
+			return options[i].Name < options[j].Name
+		})
+
+		if len(options) > 0 {
+			w.fileMap[fileName].WriteString("Use the following options to change the behavior of this command. ")
+			w.fileMap[fileName].WriteString("You can also use any of the [global flags](#global-flags) that apply to all subcommands.\n\n")
+			w.writeGroupedOptionsTable(options, fileName)
+		} else {
+			w.fileMap[fileName].WriteString("Use [global flags](#global-flags) to customize the connection to the Temporal Service for this command.\n\n")
+		}
+
+		w.collectGlobalFlags(fileName, globalOptions)
+	}
+}
+
+func (w *docWriter) writeGroupedOptionsTable(options []Option, fileName string) {
+	if len(options) == 0 {
+		return
+	}
+
+	buf := w.fileMap[fileName]
+
+	buf.WriteString("| Flag | Required | Description |\n")
+	buf.WriteString("|------|----------|-------------|\n")
+
+	for _, o := range options {
+		w.writeOptionRow(buf, o, false)
+	}
+	buf.WriteString("\n")
+}
+
 func (w *docWriter) writeSubcommand(c *Command) {
 	fileName := c.fileName()
 	prefix := strings.Repeat("#", c.depth())
@@ -255,10 +403,11 @@ func (w *docWriter) isLeafCommand(c *Command) bool {
 }
 
 func encodeJSONExample(v string) string {
-	// example: 'YourKey={"your": "value"}'
-	// results in an mdx acorn rendering error
-	// and wrapping in backticks lets it render
-	re := regexp.MustCompile(`('[a-zA-Z0-9]*={.*}')`)
+	// JSON objects in single quotes cause MDX acorn rendering errors
+	// because curly braces are interpreted as JSX expressions.
+	// Wrapping in backticks makes them render as inline code.
+	// Matches both 'Key={"value"}' and '{"key": "value"}' patterns.
+	re := regexp.MustCompile(`('\{.*?\}')`)
 	v = re.ReplaceAllString(v, "`$1`")
 	return v
 }

internal/commandsgen/parse.go

@@ -45,9 +45,9 @@ type (
 		MaximumArgs            int      `yaml:"maximum-args"`
 		IgnoreMissingEnv       bool     `yaml:"ignores-missing-env"`
 		SubcommandsOptional    bool     `yaml:"subcommands-optional"`
-		Options                []Option `yaml:"options"`
-		OptionSets             []string `yaml:"option-sets"`
-		Docs                   Docs     `yaml:"docs"`
+		Options    []Option `yaml:"options"`
+		OptionSets []string `yaml:"option-sets"`
+		Docs       Docs     `yaml:"docs"`
 	}
 
 	// Docs represents docs-only information that is not used in CLI generation.