all: improve update-readmes.go and regenerate package READMEs
Some of README.md files were initially generated by update-readmes.go,
but later had some additional information appended. Re-running update-
readmes.go blasts away those changes, and requires manually reverting
the deletions. This makes it expensive to re-run update-readmes.go to
add new READMEs or update existing ones.
Solve this problem by adding support for a special "<!-- End of auto-
generated section -->" comment and making update-readmes.go preserve
any content after it.
After this change, re-running update-readmes.go produces a zero diff.
Also set the working directory when using build.Import so that packages
inside nested modules work okay.
Add the missing first word 'Package' to ./internal/datastore/fake doc.
Change-Id: If7ba92a297eebeec8029d48d760acb1daa7f263e
Reviewed-on: https://go-review.googlesource.com/c/build/+/300229
Trust: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Alexander Rakoczy <alex@golang.org>
Reviewed-by: Carlos Amedee <carlos@golang.org>
diff --git a/cloudfns/issueswebhook/README.md b/cloudfns/issueswebhook/README.md
index ac2b7a4..3ca4b84 100644
--- a/cloudfns/issueswebhook/README.md
+++ b/cloudfns/issueswebhook/README.md
@@ -1,4 +1,13 @@
-# issueswebhook Cloud Function
+<!-- Auto-generated by x/build/update-readmes.go -->
+
+[](https://pkg.go.dev/golang.org/x/build/cloudfns/issueswebhook)
+
+# golang.org/x/build/cloudfns/issueswebhook
+
+Package issueswebhook implements a Google Cloud Function HTTP handler that expects GitHub webhook change events.
+<!-- End of auto-generated section -->
+
+## Deploying
```sh
gcloud functions deploy GitHubIssueChangeWebHook \
diff --git a/cloudfns/sendwikidiff/README.md b/cloudfns/sendwikidiff/README.md
index b8a42c6..3db8ac4 100644
--- a/cloudfns/sendwikidiff/README.md
+++ b/cloudfns/sendwikidiff/README.md
@@ -1,4 +1,13 @@
-# sendwikidiff Cloud Function
+<!-- Auto-generated by x/build/update-readmes.go -->
+
+[](https://pkg.go.dev/golang.org/x/build/cloudfns/sendwikidiff)
+
+# golang.org/x/build/cloudfns/sendwikidiff
+
+Package sendwikidiff implements a Google Cloud background function that reacts to a pubsub message containing a GitHub webhook change payload.
+<!-- End of auto-generated section -->
+
+## Deploying
```sh
gcloud functions deploy HandleWikiChangePubSub \
diff --git a/cloudfns/wikiwebhook/README.md b/cloudfns/wikiwebhook/README.md
index b70f39b..de365c8 100644
--- a/cloudfns/wikiwebhook/README.md
+++ b/cloudfns/wikiwebhook/README.md
@@ -1,4 +1,13 @@
-# wikiwebhook Cloud Function
+<!-- Auto-generated by x/build/update-readmes.go -->
+
+[](https://pkg.go.dev/golang.org/x/build/cloudfns/wikiwebhook)
+
+# golang.org/x/build/cloudfns/wikiwebhook
+
+Package wikiwebhook implements an Google Cloud Function HTTP handler that expects GitHub webhook change events.
+<!-- End of auto-generated section -->
+
+## Deploying
```sh
gcloud functions deploy GitHubWikiChangeWebHook \
diff --git a/cmd/scaleway/README.md b/cmd/scaleway/README.md
index 21054c5..9e87707 100644
--- a/cmd/scaleway/README.md
+++ b/cmd/scaleway/README.md
@@ -5,6 +5,7 @@
# golang.org/x/build/cmd/scaleway
The scaleway command creates ARM servers on Scaleway.com.
+<!-- End of auto-generated section -->
The Makefile, Dockerfiles, and kubernetes deployment file
are for running the command in daemon mode for server repair.
diff --git a/cmd/tip/README.md b/cmd/tip/README.md
index 60a8563..2967866 100644
--- a/cmd/tip/README.md
+++ b/cmd/tip/README.md
@@ -5,6 +5,7 @@
# golang.org/x/build/cmd/tip
Command tip is the tip.golang.org server, serving the latest HEAD straight from the Git oven.
+<!-- End of auto-generated section -->
## Deployment
diff --git a/cmd/updatestd/README.md b/cmd/updatestd/README.md
new file mode 100644
index 0000000..5e22205
--- /dev/null
+++ b/cmd/updatestd/README.md
@@ -0,0 +1,7 @@
+<!-- Auto-generated by x/build/update-readmes.go -->
+
+[](https://pkg.go.dev/golang.org/x/build/cmd/updatestd)
+
+# golang.org/x/build/cmd/updatestd
+
+updatestd is an experimental program that has been used to update the standard library modules as part of golang.org/issue/36905 in CL 255860 and CL 266898.
diff --git a/dashboard/README.md b/dashboard/README.md
index ac22c6f..dee8d92 100644
--- a/dashboard/README.md
+++ b/dashboard/README.md
@@ -5,6 +5,7 @@
# golang.org/x/build/dashboard
Package dashboard contains shared configuration and logic used by various pieces of the Go continuous build system.
+<!-- End of auto-generated section -->
## Deploying
diff --git a/internal/datastore/fake/README.md b/internal/datastore/fake/README.md
new file mode 100644
index 0000000..8398654
--- /dev/null
+++ b/internal/datastore/fake/README.md
@@ -0,0 +1,7 @@
+<!-- Auto-generated by x/build/update-readmes.go -->
+
+[](https://pkg.go.dev/golang.org/x/build/internal/datastore/fake)
+
+# golang.org/x/build/internal/datastore/fake
+
+Package fake provides a fake implementation of a Datastore client to use in testing.
diff --git a/internal/datastore/fake/client.go b/internal/datastore/fake/client.go
index 73278e9..6ae55b8 100644
--- a/internal/datastore/fake/client.go
+++ b/internal/datastore/fake/client.go
@@ -2,8 +2,8 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// fake provides a fake implementation of a Datastore client to use in
-// testing.
+// Package fake provides a fake implementation of a Datastore client
+// to use in testing.
package fake
import (
diff --git a/maintner/cmd/maintserve/README.md b/maintner/cmd/maintserve/README.md
index d65c9c0..4488983 100644
--- a/maintner/cmd/maintserve/README.md
+++ b/maintner/cmd/maintserve/README.md
@@ -1,11 +1,7 @@
+<!-- Auto-generated by x/build/update-readmes.go -->
+
[](https://pkg.go.dev/golang.org/x/build/maintner/cmd/maintserve)
# golang.org/x/build/maintner/cmd/maintserve
-maintserve is a program that serves Go issues over HTTP, so they can be
-viewed in a browser. It uses x/build/maintner/godata as its backing
-source of data.
-
-It statically embeds all the resources it uses, so it's possible to use
-it when offline. During that time, the corpus will not be able to update,
-and GitHub user profile pictures won't load.
+maintserve is a program that serves Go issues and CLs over HTTP, so they can be viewed in a browser.
diff --git a/update-readmes.go b/update-readmes.go
index a5e4d61..033e9c5 100644
--- a/update-readmes.go
+++ b/update-readmes.go
@@ -7,10 +7,12 @@
// The update-readmes.go tool creates or updates README.md files in
// the golang.org/x/build tree. It only updates files if they are
-// missing or were previously generated by this tool.
+// missing or were previously generated by this tool. If the file
+// contains a "<!-- End of auto-generated section -->" comment,
+// the tool leaves content in the rest of the file unmodified.
//
// The auto-generated Markdown contains the package doc synopsis
-// and a link to godoc.org for the API reference.
+// and a link to pkg.go.dev for the API reference.
package main
import (
@@ -43,7 +45,9 @@
}
pkgName := "golang.org/x/build/" + filepath.ToSlash(rest)
- pkg, err := build.Import(pkgName, "", 0)
+ bctx := build.Default
+ bctx.Dir = path // Set Dir since some x/build packages are in nested modules.
+ pkg, err := bctx.Import(pkgName, "", 0)
if err != nil {
// Skip.
return nil
@@ -66,6 +70,10 @@
if len(exist) > 0 && !bytes.Contains(exist, []byte(header)) {
return nil
}
+ var footer []byte
+ if i := bytes.Index(exist, []byte("<!-- End of auto-generated section -->")); i != -1 {
+ footer = exist[i:]
+ }
newContents := []byte(fmt.Sprintf(`<!-- %s -->
[](https://pkg.go.dev/%s)
@@ -73,7 +81,7 @@
# %s
%s
-`, header, pkgName, pkgName, pkgName, pkg.Doc))
+%s`, header, pkgName, pkgName, pkgName, pkg.Doc, footer))
if bytes.Equal(exist, newContents) {
return nil
}
