fix(internal/godocfx): rename README files to pkg-readme (#3185)

internal/godocfx/main.go

@@ -212,12 +212,12 @@ func write(outDir string, r *result) error {
 		}
 	}
 
-	for _, path := range r.extraFiles {
-		src, err := os.Open(filepath.Join(r.module.Dir, path))
+	for _, ef := range r.extraFiles {
+		src, err := os.Open(filepath.Join(r.module.Dir, ef.srcRelativePath))
 		if err != nil {
 			return err
 		}
-		dst, err := os.Create(filepath.Join(outDir, path))
+		dst, err := os.Create(filepath.Join(outDir, ef.dstRelativePath))
 		if err != nil {
 			return err
 		}

internal/godocfx/parse.go

@@ -95,19 +95,23 @@ func (i *item) addChild(c child) {
 
 var onlyGo = []string{"go"}
 
+type extraFile struct{ srcRelativePath, dstRelativePath, name string }
+
 type result struct {
 	pages      map[string]*page
 	toc        tableOfContents
 	module     *packages.Module
-	extraFiles []string
+	extraFiles []extraFile
 }
 
 // parse parses the directory into a map of import path -> page and a TOC.
 //
 // glob is the path to parse, usually ending in `...`. glob is passed directly
 // to packages.Load as-is.
 //
-// extraFiles is a list of paths relative to the module root to include.
+// workingDir is the directory to use to run go commands.
+//
+// optionalExtraFiles is a list of paths relative to the module root to include.
 func parse(glob string, workingDir string, optionalExtraFiles []string) (*result, error) {
 	pages := map[string]*page{}
 
@@ -119,10 +123,22 @@ func parse(glob string, workingDir string, optionalExtraFiles []string) (*result
 
 	// Filter out extra files that don't exist because some modules don't have a
 	// README.
-	extraFiles := []string{}
+	extraFiles := []extraFile{}
 	for _, f := range optionalExtraFiles {
 		if _, err := os.Stat(filepath.Join(module.Dir, f)); err == nil {
-			extraFiles = append(extraFiles, f)
+			dst := f
+			dir := filepath.Dir(f)
+			base := filepath.Base(f)
+			name := strings.TrimSuffix(base, filepath.Ext(base))
+			name = strings.Title(name)
+			if name == "README" {
+				dst = filepath.Join(dir, "pkg-readme.md")
+			}
+			extraFiles = append(extraFiles, extraFile{
+				srcRelativePath: f,
+				dstRelativePath: dst,
+				name:            name,
+			})
 		}
 	}
 
@@ -317,20 +333,17 @@ func processExamples(exs []*doc.Example, fset *token.FileSet) []example {
 	return result
 }
 
-func buildTOC(mod string, pis []pkgInfo, extraFiles []string) tableOfContents {
+func buildTOC(mod string, pis []pkgInfo, extraFiles []extraFile) tableOfContents {
 	toc := tableOfContents{}
 
 	modTOC := &tocItem{
 		UID:  mod, // Assume the module root has a package.
 		Name: mod,
 	}
-	for _, path := range extraFiles {
-		base := filepath.Base(path)
-		name := strings.TrimSuffix(base, filepath.Ext(base))
-		name = strings.Title(name)
+	for _, ef := range extraFiles {
 		modTOC.addItem(&tocItem{
-			Href: path,
-			Name: name,
+			Href: ef.dstRelativePath,
+			Name: ef.name,
 		})
 	}
 

internal/godocfx/testdata/golden/toc.yml

@@ -3,4 +3,4 @@
   name: cloud.google.com/go/storage
   items:
   - name: README
-    href: README.md
+    href: pkg-readme.md