From d3a85719be411b692aede3331abb29b5a7b3da9a Mon Sep 17 00:00:00 2001
From: Tyler Bui-Palsulich <26876514+tbpg@users.noreply.github.com>
Date: Tue, 10 Nov 2020 14:34:11 -0500
Subject: [PATCH] fix(internal/godocfx): rename README files to pkg-readme
 (#3185)

---
 internal/godocfx/main.go                      |  6 ++--
 internal/godocfx/parse.go                     | 35 +++++++++++++------
 .../golden/{README.md => pkg-readme.md}       |  0
 internal/godocfx/testdata/golden/toc.yml      |  2 +-
 4 files changed, 28 insertions(+), 15 deletions(-)
 rename internal/godocfx/testdata/golden/{README.md => pkg-readme.md} (100%)

diff --git a/internal/godocfx/main.go b/internal/godocfx/main.go
index 1d88bc906f4..395a574b374 100644
--- a/internal/godocfx/main.go
+++ b/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
 		}
diff --git a/internal/godocfx/parse.go b/internal/godocfx/parse.go
index 35e8bb699bd..b7ba6ea1667 100644
--- a/internal/godocfx/parse.go
+++ b/internal/godocfx/parse.go
@@ -95,11 +95,13 @@ 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.
@@ -107,7 +109,9 @@ type result struct {
 // 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,
 		})
 	}
 
diff --git a/internal/godocfx/testdata/golden/README.md b/internal/godocfx/testdata/golden/pkg-readme.md
similarity index 100%
rename from internal/godocfx/testdata/golden/README.md
rename to internal/godocfx/testdata/golden/pkg-readme.md
diff --git a/internal/godocfx/testdata/golden/toc.yml b/internal/godocfx/testdata/golden/toc.yml
index 3b7294c60cb..4e31bd65dbb 100644
--- a/internal/godocfx/testdata/golden/toc.yml
+++ b/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