docs(librarian): add godoc for nested commands (#2225)

Added Go's versions of partials to the text template so we can recurse
through nested commands and print all of thier help text godoc.

Fixes: #207

Author: codyoss

internal/librarian/doc.go

@@ -139,6 +139,118 @@ Commands:
 	init                       initiates a release by creating a release pull request.
 	tag-and-release            tags and creates a GitHub release for a merged pull request.
 
+# release init
+
+The 'release init' command is the primary entry point for initiating
+a new release. It automates the creation of a release pull request by parsing
+conventional commits, determining the next semantic version for each library,
+and generating a changelog. Librarian is environment aware and will check if the
+current directory is the root of a librarian repository. If you are not
+executing in such a directory the '--repo' flag must be provided.
+
+This command scans the git history since the last release, identifies changes
+(feat, fix, BREAKING CHANGE), and calculates the appropriate version bump
+according to semver rules. It then delegates all language-specific file
+modifications, such as updating a CHANGELOG.md or bumping the version in a pom.xml,
+to the configured language-specific container.
+
+By default, 'release init' leaves the changes in your local working directory
+for inspection. Use the '--push' flag to automatically commit the changes to
+a new branch and create a pull request on GitHub. The '--commit' flag may be
+used to create a local commit without creating a pull request; this flag is
+ignored if '--push' is also specified.
+
+Examples:
+
+	# Create a release PR for all libraries with pending changes.
+	librarian release init --push
+
+	# Create a release PR for a single library.
+	librarian release init --library=secretmanager --push
+
+	# Manually specify a version for a single library, overriding the calculation.
+	librarian release init --library=secretmanager --library-version=2.0.0 --push
+
+Usage:
+
+	librarian release init [flags]
+
+Flags:
+
+	-branch string
+	  	The branch to use with remote code repositories. This is used to specify
+	  	which branch to clone and which branch to use as the base for a pull
+	  	request. (default "main")
+	-commit
+	  	If true, librarian will create a commit for the release but not create
+	  	a pull request. This flag is ignored if push is set to true.
+	-image string
+	  	Language specific image used to invoke code generation and releasing.
+	  	If not specified, the image configured in the state.yaml is used.
+	-library string
+	  	The library ID to generate or release (e.g. google-cloud-secretmanager-v1).
+	  	This corresponds to a releasable language unit.
+	-library-version string
+	  	Overrides the automatic semantic version calculation and forces a specific
+	  	version for a library. Requires the --library flag to be specified.
+	-output string
+	  	Working directory root. When this is not specified, a working directory
+	  	will be created in /tmp.
+	-push
+	  	If true, Librarian will create a commit and a pull request for the changes.
+	  	A GitHub token with push access must be provided via the
+	  	LIBRARIAN_GITHUB_TOKEN environment variable.
+	-repo string
+	  	Code repository where the generated code will reside. Can be a remote
+	  	in the format of a remote URL such as https://github.com/{owner}/{repo} or a
+	  	local file path like /path/to/repo. Both absolute and relative paths are
+	  	supported. If not specified, will try to detect if the current working directory
+	  	is configured as a language repository.
+
+# release tag-and-release
+
+The 'tag-and-release' command is the final step in the release
+process. It is designed to be run after a release pull request, created by
+'release init', has been merged.
+
+This command's primary responsibilities are to:
+
+  - Create a Git tag for each library version included in the merged pull request.
+  - Create a corresponding GitHub Release for each tag, using the release notes
+    from the pull request body.
+  - Update the pull request's label from 'release:pending' to 'release:done' to
+    mark the process as complete.
+
+You can target a specific merged pull request using the '--pr' flag. If no pull
+request is specified, the command will automatically search for and process all
+merged pull requests with the 'release:pending' label from the last 30 days.
+
+Examples:
+
+	# Tag and create a GitHub release for a specific merged PR.
+	librarian release tag-and-release --repo=https://github.com/googleapis/google-cloud-go --pr=https://github.com/googleapis/google-cloud-go/pull/123
+
+	# Find and process all pending merged release PRs in a repository.
+	librarian release tag-and-release --repo=https://github.com/googleapis/google-cloud-go
+
+Usage:
+
+	librarian release tag-and-release [arguments]
+
+Flags:
+
+	-pr string
+	  	The URL of a pull request to operate on.
+	  	It should be in the format of https://github.com/{owner}/{repo}/pull/{number}.
+	  	If not specified, will search for all merged pull requests with the label
+	  	"release:pending" in the last 30 days.
+	-repo string
+	  	Code repository where the generated code will reside. Can be a remote
+	  	in the format of a remote URL such as https://github.com/{owner}/{repo} or a
+	  	local file path like /path/to/repo. Both absolute and relative paths are
+	  	supported. If not specified, will try to detect if the current working directory
+	  	is configured as a language repository.
+
 # version
 
 Version prints version information for the librarian binary.

internal/librarian/doc_generate.go

@@ -53,20 +53,26 @@ Usage:
 	librarian <command> [arguments]
 
 The commands are:
-{{range .Commands}}
+{{range .Commands}}{{template "command" .}}{{end}}
+*/
+package librarian
+
+{{define "command"}}
 
 # {{.Name}}
 
 {{.HelpText}}
+{{if .Commands}}
+{{range .Commands}}{{template "command" .}}{{end}}
+{{end}}
 {{end}}
-*/
-package librarian
 `
 
 // CommandDoc holds the documentation for a single CLI command.
 type CommandDoc struct {
 	Name     string
 	HelpText string
+	Commands []CommandDoc
 }
 
 func main() {
@@ -87,36 +93,11 @@ func run() error {
 }
 
 func processFile() error {
-	// Get the help text.
-	cmd := exec.Command("go", "run", "../../cmd/librarian/")
-	var out bytes.Buffer
-	cmd.Stdout = &out
-	cmd.Stderr = &out
-	err := cmd.Run()
-	if err != nil {
-		// The command exits with status 1 if no subcommand is given, which is
-		// the case when we are generating the help text. We can ignore the
-		// error if there is output.
-		if out.Len() == 0 {
-			return fmt.Errorf("cmd.Run() failed with %s\n%s", err, out.String())
-		}
-	}
-	helpText := out.Bytes()
-
-	commandNames, err := extractCommandNames(helpText)
+	commands, err := buildCommandDocs("")
 	if err != nil {
 		return err
 	}
 
-	var commands []CommandDoc
-	for _, name := range commandNames {
-		help, err := getCommandHelp(name)
-		if err != nil {
-			return fmt.Errorf("getting help for command %s: %w", name, err)
-		}
-		commands = append(commands, CommandDoc{Name: name, HelpText: help})
-	}
-
 	docFile, err := os.Create("doc.go")
 	if err != nil {
 		return fmt.Errorf("could not create doc.go: %v", err)
@@ -130,8 +111,62 @@ func processFile() error {
 	return nil
 }
 
-func getCommandHelp(command string) (string, error) {
-	cmd := exec.Command("go", "run", "../../cmd/librarian/", command, "--help")
+func buildCommandDocs(parentCommand string) ([]CommandDoc, error) {
+	var parentParts []string
+	if parentCommand != "" {
+		parentParts = strings.Fields(parentCommand)
+	}
+
+	// Get help text for parent to find subcommands.
+	args := []string{"run", "../../cmd/librarian/"}
+	args = append(args, parentParts...)
+	cmd := exec.Command("go", args...)
+	var out bytes.Buffer
+	cmd.Stdout = &out
+	cmd.Stderr = &out
+	// Ignore error, help text is printed on error when no subcommand is provided.
+	_ = cmd.Run()
+
+	commandNames, err := extractCommandNames(out.Bytes())
+	if err != nil {
+		// Not an error, just means no subcommands.
+		return nil, nil
+	}
+
+	var commands []CommandDoc
+	for _, name := range commandNames {
+		fullCommandName := name
+		if parentCommand != "" {
+			fullCommandName = parentCommand + " " + name
+		}
+
+		helpText, err := getCommandHelpText(fullCommandName)
+		if err != nil {
+			return nil, fmt.Errorf("getting help text for command %s: %w", fullCommandName, err)
+		}
+
+		// Recurse.
+		subCommands, err := buildCommandDocs(fullCommandName)
+		if err != nil {
+			return nil, err
+		}
+
+		commands = append(commands, CommandDoc{
+			Name:     fullCommandName,
+			HelpText: helpText,
+			Commands: subCommands,
+		})
+	}
+
+	return commands, nil
+}
+
+func getCommandHelpText(command string) (string, error) {
+	parts := strings.Fields(command)
+	args := []string{"run", "../../cmd/librarian/"}
+	args = append(args, parts...)
+	args = append(args, "--help")
+	cmd := exec.Command("go", args...)
 	var out bytes.Buffer
 	cmd.Stdout = &out
 	cmd.Stderr = &out