feat(internal/librarian/golang): add README generation (#3898)

Generate a README.md file for each Go client library module.

For #3617

Author: julieqiu

internal/librarian/golang/generate.go

@@ -17,16 +17,25 @@ package golang
 
 import (
 	"context"
+	_ "embed"
 	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
+	"text/template"
 
 	"github.com/googleapis/librarian/internal/command"
 	"github.com/googleapis/librarian/internal/config"
 	"github.com/googleapis/librarian/internal/serviceconfig"
 )
 
+var (
+	//go:embed template/_README.md.txt
+	readmeTmpl string
+
+	readmeTmplParsed = template.Must(template.New("readme").Parse(readmeTmpl))
+)
+
 // Generate generates a Go client library.
 func Generate(ctx context.Context, library *config.Library, googleapisDir string) error {
 	if len(library.APIs) == 0 {
@@ -70,6 +79,13 @@ func Generate(ctx context.Context, library *config.Library, googleapisDir string
 	}
 
 	moduleRoot := filepath.Join(outdir, library.Name)
+	absModuleRoot, err := filepath.Abs(moduleRoot)
+	if err != nil {
+		return err
+	}
+	if !strings.HasPrefix(absModuleRoot, outdir+string(filepath.Separator)) && absModuleRoot != outdir {
+		return fmt.Errorf("invalid library name: path traversal detected")
+	}
 	if err := generateInternalVersionFile(moduleRoot, library.Version); err != nil {
 		return err
 	}
@@ -78,6 +94,13 @@ func Generate(ctx context.Context, library *config.Library, googleapisDir string
 			return err
 		}
 	}
+	api, err := serviceconfig.Find(googleapisDir, library.APIs[0].Path)
+	if err != nil {
+		return err
+	}
+	if err := generateREADME(library, api, moduleRoot); err != nil {
+		return err
+	}
 	return nil
 }
 
@@ -293,3 +316,22 @@ func collectProtoFiles(googleapisDir, apiPath string, nestedProtos []string) ([]
 	}
 	return files, nil
 }
+
+func generateREADME(library *config.Library, api *serviceconfig.API, moduleRoot string) error {
+	if len(library.APIs) == 0 {
+		return fmt.Errorf("no APIs configured")
+	}
+	f, err := os.Create(filepath.Join(moduleRoot, "README.md"))
+	if err != nil {
+		return err
+	}
+	err = readmeTmplParsed.Execute(f, map[string]string{
+		"Name":       api.Title,
+		"ModulePath": modulePath(library),
+	})
+	cerr := f.Close()
+	if err != nil {
+		return err
+	}
+	return cerr
+}

internal/librarian/golang/generate_test.go

@@ -17,10 +17,12 @@ package golang
 import (
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"github.com/google/go-cmp/cmp"
 	"github.com/googleapis/librarian/internal/config"
+	"github.com/googleapis/librarian/internal/serviceconfig"
 	"github.com/googleapis/librarian/internal/testhelper"
 )
 
@@ -48,6 +50,7 @@ func TestGenerate(t *testing.T) {
 				"secretmanager/apiv1/secretmanagerpb/service.pb.go",
 				"secretmanager/apiv1/version.go",
 				"secretmanager/internal/version.go",
+				"secretmanager/README.md",
 			},
 			removed: []string{
 				"cloud.google.com",
@@ -208,3 +211,37 @@ func main() {
 		t.Errorf("mismatch (-want +got):\n%s", diff)
 	}
 }
+
+func TestGenerateREADME(t *testing.T) {
+	dir := t.TempDir()
+	moduleRoot := filepath.Join(dir, "secretmanager")
+	if err := os.MkdirAll(moduleRoot, 0755); err != nil {
+		t.Fatal(err)
+	}
+
+	library := &config.Library{
+		Name:   "secretmanager",
+		Output: dir,
+		APIs:   []*config.API{{Path: "google/cloud/secretmanager/v1"}},
+	}
+
+	api, err := serviceconfig.Find(googleapisDir, library.APIs[0].Path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := generateREADME(library, api, moduleRoot); err != nil {
+		t.Fatal(err)
+	}
+
+	content, err := os.ReadFile(filepath.Join(moduleRoot, "README.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := string(content)
+	if !strings.Contains(s, "Secret Manager API") {
+		t.Errorf("want title in README, got:\n%s", s)
+	}
+	if !strings.Contains(s, "cloud.google.com/go/secretmanager") {
+		t.Errorf("want module path in README, got:\n%s", s)
+	}
+}

internal/librarian/golang/template/_README.md.txt

@@ -0,0 +1,55 @@
+# {{.Name}}
+
+[![Go Reference](https://pkg.go.dev/badge/{{.ModulePath}}.svg)](https://pkg.go.dev/{{.ModulePath}})
+
+Go Client Library for {{.Name}}.
+
+## Install
+
+```bash
+go get {{.ModulePath}}
+```
+
+## Stability
+
+The stability of this module is indicated by SemVer.
+
+However, a `v1+` module may have breaking changes in two scenarios:
+
+* Packages with `alpha` or `beta` in the import path
+* The GoDoc has an explicit stability disclaimer (for example, for an experimental feature).
+
+### Which package to use?
+
+Generated client library surfaces can be found in packages whose import path
+ends in `.../apivXXX`. The `XXX` could be something like `1` or `2` in the case
+of a stable service backend or may be like `1beta2` or `2beta` in the case of a
+more experimental service backend. Because of this fact, a given module can have
+multiple clients for different service backends. In these cases it is generally
+recommended to use clients with stable service backends, with import suffixes like
+`apiv1`, unless you need to use features that are only present in a beta backend
+or there is not yet a stable backend available.
+
+## Google Cloud Samples
+
+To browse ready to use code samples check [Google Cloud Samples](https://cloud.google.com/docs/samples?l=go).
+
+## Go Version Support
+
+See the [Go Versions Supported](https://github.com/googleapis/google-cloud-go#go-versions-supported)
+section in the root directory's README.
+
+## Authorization
+
+See the [Authorization](https://github.com/googleapis/google-cloud-go#authorization)
+section in the root directory's README.
+
+## Contributing
+
+Contributions are welcome. Please, see the [CONTRIBUTING](https://github.com/GoogleCloudPlatform/google-cloud-go/blob/main/CONTRIBUTING.md)
+document for details.
+
+Please note that this project is released with a Contributor Code of Conduct.
+By participating in this project you agree to abide by its terms. See
+[Contributor Code of Conduct](https://github.com/GoogleCloudPlatform/google-cloud-go/blob/main/CONTRIBUTING.md#contributor-code-of-conduct)
+for more information.