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

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

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>

2026-04-22 15:13:09 -07: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