webnet/tailscale
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Brad Fitzpatrick
2026-04-22 21:08:16 +00:00
committed by Brad Fitzpatrick
parent 311dd3839d
commit a7d8aeb8ae
11 changed files with 399 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tsnet/example/tsnet-services/tsnet-services.go
+3 -4
View File
@@ -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:
//