mirror of https://github.com/tailscale/tailscale.git synced 2026-05-05 20:26:47 +02:00

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

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>

2026-04-22 21:53:46 +00:00

1.3 KiB

Raw Permalink Blame History

tsnet-services

The tsnet-services example demonstrates how to use tsnet with Services.

To run this example yourself:

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.
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).
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.
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": ["*"],
],

1.3 KiB Raw Permalink Blame History

tsnet-services

1.3 KiB

Raw Permalink Blame History