chore: add doc.go in cmd/automation (#2810)

Add an empty doc.go in `cmd/automation`. 

In addition, modify `doc_generate.go` so that it can be used to generate
docs for different packages.

For #2416

Author: JoeWang1127

cmd/automation/doc.go

@@ -0,0 +1,29 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//	https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:generate go run -tags docgen ../doc_generate.go -cmd .
+
+/*
+Librarian manages Google API client libraries by automating onboarding,
+regeneration, and release. It runs language-agnostic workflows while
+delegating language-specific tasks—such as code generation, building, and
+testing—to Docker images.
+
+Usage:
+
+	librarian <command> [arguments]
+
+The commands are:
+*/
+package main

cmd/automation/main.go

@@ -12,10 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Librarian manages Google API client libraries by automating onboarding,
-// regeneration, and release. It runs language‑agnostic workflows while
-// delegating language‑specific tasks—such as code generation, building, and
-// testing—to Docker images.
 package main
 
 import (

cmd/librarian/doc_generate.go renamed to cmd/doc_generate.go

@@ -19,6 +19,7 @@ package main
 import (
 	"bytes"
 	"errors"
+	"flag"
 	"fmt"
 	"log"
 	"os"
@@ -41,7 +42,7 @@ const docTemplate = `// Copyright 2025 Google LLC
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//go:generate go run -tags docgen doc_generate.go
+//go:generate go run -tags docgen ../doc_generate.go -cmd .
 
 /*
 Librarian manages Google API client libraries by automating onboarding,
@@ -76,7 +77,13 @@ type CommandDoc struct {
 	Commands []CommandDoc
 }
 
+var cmdPath = flag.String("cmd", "", "Path to the command to generate docs for (e.g., ../../cmd/librarian)")
+
 func main() {
+	flag.Parse()
+	if *cmdPath == "" {
+		log.Fatal("must specify -cmd flag")
+	}
 	if err := run(); err != nil {
 		log.Fatal(err)
 	}
@@ -164,7 +171,7 @@ func buildCommandDocs(parentCommand string) ([]CommandDoc, error) {
 
 func getCommandHelpText(command string) (string, error) {
 	parts := strings.Fields(command)
-	args := []string{"run", "../../cmd/librarian/"}
+	args := []string{"run", *cmdPath}
 	args = append(args, parts...)
 	args = append(args, "--help")
 	cmd := exec.Command("go", args...)

cmd/doc_generate_test.go

@@ -0,0 +1,60 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//	https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"bytes"
+	"os/exec"
+	"testing"
+)
+
+func TestGoGenerateLibrarianDoc(t *testing.T) {
+	for _, test := range []struct {
+		name    string
+		docFile string
+	}{
+		{
+			name:    "automation_doc",
+			docFile: "cmd/automation/doc.go",
+		},
+		{
+			name:    "librarian_doc",
+			docFile: "cmd/librarian/doc.go",
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			cmd := exec.Command("go", "generate", "./...")
+			var stderr, stdout bytes.Buffer
+			cmd.Stderr = &stderr
+			cmd.Stdout = &stdout
+			t.Log(stderr.String())
+			t.Log(stdout.String())
+			if err := cmd.Run(); err != nil {
+				t.Fatalf("%v: %v", cmd, err)
+			}
+			cmd = exec.Command("git", "diff", "--exit-code", "--", test.docFile)
+			if err := cmd.Run(); err != nil {
+				t.Errorf("go generate produced a diff, please run `go generate ./...` and commit the changes")
+				cmd = exec.Command("git", "diff", "--", test.docFile)
+				out, err := cmd.CombinedOutput()
+				if err != nil {
+					t.Fatalf("git diff failed: %v", err)
+				}
+				t.Logf("diff:\n%s", out)
+			}
+		})
+	}
+}

cmd/librarian/doc.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//go:generate go run -tags docgen doc_generate.go
+//go:generate go run -tags docgen ../doc_generate.go -cmd .
 
 /*
 Librarian manages Google API client libraries by automating onboarding,