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

Adds a CI check and Makefile target 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 `make genreadme` with no
arguments.

The genreadme workflow runs `make genreadme` 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: Iade21dc87921ab2bbb65951e5fb373b597fed29e
Signed-off-by: Walter Poupore <walterp@tailscale.com>

1 files changed, 46 insertions, 0 deletions

diff --git a/.github/workflows/genreadme.yml b/.github/workflows/genreadme.yml
new file mode 100644
index 000000000..ae930c3fd
--- /dev/null
+++ b/.github/workflows/genreadme.yml
@@ -0,0 +1,46 @@
+name: genreadme
+
+env:
+  HOME: ${{ github.workspace }}
+  GOMODCACHE: ${{ github.workspace }}/gomodcache
+  CMD_GO_USE_GIT_HASH: "true"
+
+on:
+  push:
+    branches:
+      - main
+      - "release-branch/*"
+    paths:
+      - "**.go"
+      - "misc/genreadme/**"
+      - "Makefile"
+      - ".github/workflows/genreadme.yml"
+  pull_request:
+    paths:
+      - "**.go"
+      - "misc/genreadme/**"
+      - "Makefile"
+      - ".github/workflows/genreadme.yml"
+
+jobs:
+  genreadme:
+    runs-on: [ self-hosted, linux ]
+    timeout-minutes: 5
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          path: src
+
+      - name: Check 'genreadme' is clean
+        working-directory: src
+        run: |
+          make genreadme
+          echo
+          echo
+          if [[ $(git status -s) ]]; then
+            git status -s
+            echo "The files above need updating. Please run 'make genreadme'."
+            exit 1
+          fi