misc/genreadme,tempfork/pkgdoc,tsnet: generate README.md files from godocfserb/main

Adds a CI check to keep opted-in directories' README.md files in sync
with their package godoc. For now tsnet (and its sub-packages under
tsnet/example) is the only opted-in tree. The list of directories
lives in misc/genreadme/genreadme.go as defaultRoots, so CI and humans
both just run `./tool/go run ./misc/genreadme` with no arguments.

The check piggybacks on the existing go_generate job in test.yml and
fails if any README.md is out of date, pointing the user at the same
command.

Along the way:

 - tempfork/pkgdoc now emits Markdown instead of plain text: headings
   become level-2 with no {#hdr-...} anchors, and [Symbol] doc links
   resolve to pkg.go.dev URLs, including for symbols in the current
   package (which the default Printer would otherwise emit as bare
   #Name fragments with no backing anchor in a README). Parsing no
   longer uses parser.ImportsOnly, so doc.Package knows the package's
   symbols and can resolve [Symbol] links at all.

 - genreadme also emits a pkg.go.dev Go Reference badge at the top of
   a library package's README; suppressed for package main.

 - tsnet/tsnet.go's package godoc is expanded in idiomatic godoc
   syntax — [Type], [Type.Method], reference-style [link]: URL
   definitions — rather than Markdown-flavored [text](url) or
   backtick-quoted identifiers, so that both pkg.go.dev and the
   generated README.md render cleanly from a single source.

Fixes #19431
Fixes #19483
Fixes #19470

Change-Id: I8ca37e9e7b3bd446b8bfa7a91ac548f142688cb1
Co-authored-by: Brad Fitzpatrick <bradfitz@tailscale.com>
Signed-off-by: Walter Poupore <walterp@tailscale.com>
Signed-off-by: Brad Fitzpatrick <bradfitz@tailscale.com>

6 files changed, 59 insertions, 4 deletions

diff --git a/tsnet/example/tshello/README.md b/tsnet/example/tshello/README.md
new file mode 100644
index 000000000..5d9d81829
--- /dev/null
+++ b/tsnet/example/tshello/README.md
@@ -0,0 +1,5 @@
+<!-- README.md auto-generated by misc/genreadme; DO NOT EDIT. (or remove this line) -->
+
+# tshello
+
+The tshello server demonstrates how to use Tailscale as a library.
diff --git a/tsnet/example/tsnet-funnel/README.md b/tsnet/example/tsnet-funnel/README.md
new file mode 100644
index 000000000..2b3031bed
--- /dev/null
+++ b/tsnet/example/tsnet-funnel/README.md
@@ -0,0 +1,9 @@
+<!-- README.md auto-generated by misc/genreadme; DO NOT EDIT. (or remove this line) -->
+
+# tsnet-funnel
+
+The tsnet-funnel server demonstrates how to use tsnet with Funnel.
+
+To use it, generate an auth key from the Tailscale admin panel and run the demo with the key:
+
+	TS_AUTHKEY=<yourkey> go run tsnet-funnel.go
diff --git a/tsnet/example/tsnet-http-client/README.md b/tsnet/example/tsnet-http-client/README.md
new file mode 100644
index 000000000..24aba97c8
--- /dev/null
+++ b/tsnet/example/tsnet-http-client/README.md
@@ -0,0 +1,5 @@
+<!-- README.md auto-generated by misc/genreadme; DO NOT EDIT. (or remove this line) -->
+
+# tsnet-http-client
+
+The tshello server demonstrates how to use Tailscale as a library.
diff --git a/tsnet/example/tsnet-services/README.md b/tsnet/example/tsnet-services/README.md
new file mode 100644
index 000000000..18bc072d7
--- /dev/null
+++ b/tsnet/example/tsnet-services/README.md
@@ -0,0 +1,32 @@
+<!-- README.md auto-generated by misc/genreadme; DO NOT EDIT. (or remove this line) -->
+
+# tsnet-services
+
+The tsnet-services example demonstrates how to use tsnet with Services.
+
+To run this example yourself:
+
+ 1. Add access controls which (i) define a new ACL tag, (ii) allow the demo node to host the Service, and (iii) allow peers on the tailnet to reach the Service. A sample ACL policy is provided below.
+ 2. [Generate an auth key](https://tailscale.com/kb/1085/auth-keys#generate-an-auth-key) using the Tailscale admin panel. When doing so, add your new tag to your key (Service hosts must be tagged nodes).
+ 3. [Define a Service](https://tailscale.com/kb/1552/tailscale-services#step-1-define-a-tailscale-service). For the purposes of this demo, it must be defined to listen on TCP port 443. Note that you only need to follow Step 1 in the linked document.
+ 4. Run the demo on the command line (step 4 command shown below).
+
+Command for step 4:
+
+	TS_AUTHKEY=<yourkey> go run tsnet-services.go -service <service-name>
+
+The following is a sample ACL policy for step 1:
+
+	"tagOwners": {
+	   "tag:tsnet-demo-host": ["autogroup:member"],
+	},
+	"autoApprovers": {
+	   "services": {
+	      "svc:tsnet-demo": ["tag:tsnet-demo-host"],
+	   },
+	},
+	"grants": [
+	   "src": ["*"],
+	   "dst": ["svc:tsnet-demo"],
+	   "ip": ["*"],
+	],
diff --git a/tsnet/example/tsnet-services/tsnet-services.go b/tsnet/example/tsnet-services/tsnet-services.go
index d72fd68fd..4604e8d3f 100644
--- a/tsnet/example/tsnet-services/tsnet-services.go
+++ b/tsnet/example/tsnet-services/tsnet-services.go
@@ -8,17 +8,16 @@
 //  1. Add access controls which (i) define a new ACL tag, (ii) allow the demo
 //     node to host the Service, and (iii) allow peers on the tailnet to reach
 //     the Service. A sample ACL policy is provided below.
-//
 //  2. [Generate an auth key] using the Tailscale admin panel. When doing so, add
 //     your new tag to your key (Service hosts must be tagged nodes).
-//
 //  3. [Define a Service]. For the purposes of this demo, it must be defined to
 //     listen on TCP port 443. Note that you only need to follow Step 1 in the
 //     linked document.
+//  4. Run the demo on the command line (step 4 command shown below).
 //
-//  4. Run the demo on the command line:
+// Command for step 4:
 //
-//     TS_AUTHKEY=<yourkey> go run tsnet-services.go -service <service-name>
+//	TS_AUTHKEY=<yourkey> go run tsnet-services.go -service <service-name>
 //
 // The following is a sample ACL policy for step 1:
 //
diff --git a/tsnet/example/web-client/README.md b/tsnet/example/web-client/README.md
new file mode 100644
index 000000000..6b4c42235
--- /dev/null
+++ b/tsnet/example/web-client/README.md
@@ -0,0 +1,5 @@
+<!-- README.md auto-generated by misc/genreadme; DO NOT EDIT. (or remove this line) -->
+
+# web-client
+
+The web-client command demonstrates serving the Tailscale web client over tsnet.