docs: start generating package godoc (#1956)

Created a means for us to generate the doc.go file based off output from
the help text. There is much more doc that still needs to be put into
this file but wanted to land this as a proof of concept at least.

Updates: #207

Author: codyoss

.github/workflows/librarian.yaml

@@ -49,6 +49,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: 'go.mod'
+      - name: Install tools
+        run: |
+          set -e
+          curl -fSSL -o /tmp/protoc.zip https://github.com/protocolbuffers/protobuf/releases/download/v28.3/protoc-28.3-linux-x86_64.zip
+          cd /usr/local
+          sudo unzip -x /tmp/protoc.zip
+          protoc --version
+          go install github.com/google/yamlfmt/cmd/[email protected]
+          go install golang.org/x/tools/cmd/goimports@latest
       - uses: docker/setup-docker-action@v4
       - name: Build the test image
         run: |

internal/librarian/doc.go

@@ -0,0 +1,32 @@
+// 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
+
+/*
+Package librarian contains the business logic for the Librarian CLI.
+Implementation details for interacting with other systems (Git, GitHub,
+Docker etc.) are abstracted into other packages.
+
+Usage:
+
+	librarian <command> [arguments]
+
+The commands are:
+
+	generate                   generates client library code for a single API
+	release                    manages releases of libraries.
+	version                    prints the version information
+*/
+package librarian

internal/librarian/doc_generate.go

@@ -0,0 +1,121 @@
+// Copyright 2024 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:build docgen
+
+package main
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"log"
+	"os"
+	"os/exec"
+	"strings"
+	"text/template"
+)
+
+const docTemplate = `// 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
+
+/*
+Package librarian contains the business logic for the Librarian CLI.
+Implementation details for interacting with other systems (Git, GitHub,
+Docker etc.) are abstracted into other packages.
+
+Usage:
+
+	librarian <command> [arguments]
+
+The commands are:
+{{.Commands}}
+*/
+package librarian
+`
+
+func main() {
+	if err := run(); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func run() error {
+	if err := processFile(); err != nil {
+		return err
+	}
+	cmd := exec.Command("goimports", "-w", "doc.go")
+	if err := cmd.Run(); err != nil {
+		log.Fatalf("goimports: %v", err)
+	}
+	return nil
+}
+
+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()
+
+	commands, err := extractCommands(helpText)
+
+	docFile, err := os.Create("doc.go")
+	if err != nil {
+		return fmt.Errorf("could not create doc.go: %v", err)
+	}
+	defer docFile.Close()
+
+	tmpl := template.Must(template.New("doc").Parse(docTemplate))
+	if err := tmpl.Execute(docFile, struct{ Commands string }{Commands: string(commands)}); err != nil {
+		return fmt.Errorf("could not execute template: %v", err)
+	}
+	return nil
+}
+
+func extractCommands(helpText []byte) ([]byte, error) {
+	const (
+		commandsHeader = "Commands:\n\n"
+	)
+	ss := string(helpText)
+	start := strings.Index(ss, commandsHeader)
+	if start == -1 {
+		return nil, errors.New("could not find commands header")
+	}
+	start += len(commandsHeader)
+	return []byte(ss[start:]), nil
+}

internal/librarian/doc_generate_test.go

@@ -0,0 +1,41 @@
+// 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 librarian
+
+import (
+	"bytes"
+	"os/exec"
+	"testing"
+)
+
+func TestGoGenerate(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")
+	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")
+		out, _ := cmd.CombinedOutput()
+		t.Logf("diff:\n%s", out)
+	}
+}

internal/librarian/librarian.go

@@ -12,9 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package librarian contains the business logic for the Librarian CLI.
-// Implementation details for interacting with other systems (Git, GitHub,
-// Docker etc.) are abstracted into other packages.
 package librarian
 
 import (
@@ -53,7 +50,7 @@ func Run(ctx context.Context, arg ...string) error {
 	}
 	if len(arg) == 0 {
 		CmdLibrarian.Flags.Usage()
-		return fmt.Errorf("command not specified")
+		return nil
 	}
 	cmd, arg, err := lookupCommand(CmdLibrarian, arg)
 	if err != nil {