Documentation
¶
Overview ¶
Package doc cmd/skywire/commands/doc/doc.go c4-vis-cli subcommand that walks the cobra tree rooted at the umbrella `skywire` binary and emits one markdown page per command under docs/skywire/ mirroring the cobra command hierarchy.
Why this exists: the cmd/{skywire,skywire-cli,skycoin-skywire,svc, dmsg}/README.md files used to be hand-maintained. They drifted, they leaked the build-host's reward address, and they triplicated each other (skywire and skycoin-skywire each re-embedded the full cli subtree). This generator replaces all of that with a single source- of-truth: the live cobra tree.
Output shape:
docs/skywire/README.md — `skywire` help docs/skywire/cli/README.md — `skywire cli` help + links to children docs/skywire/cli/dmsg/README.md — `skywire cli dmsg` help + links docs/skywire/cli/dmsg/cat/README.md — `skywire cli dmsg cat` help docs/skywire/cli/dmsg/cat/listen/README.md
Each page links upward to its parent and downward to its children, so readers can navigate the tree without an external index.
Sanitization: see sanitize() below — replaces any xpub-prefixed extended key with the Skycoin genesis address. The all-zeros cipher.SecKey sentinel is left untouched (it's the literal default rendered for SecKey flags and conveys "no key supplied" semantics).
Package doc cmd/skywire/commands/doc/md_render.go
Package doc cmd/skywire/commands/doc/serve.go c1-cli-doc `skywire doc serve` — the documentation, served by the thing it documents.
Two sources, one site:
/ the cobra tree, walked live by collect() — zero embedded
bytes, and it cannot drift from the binary because it IS the
binary's command tree
/prose/… the hand-written markdown embedded by package docs
Why this exists rather than a link to the docs site: in the browser visor the nested browser has no transport until someone starts a visor, so a clearnet fetch of the docs strands on a placeholder (measured live). Served on the virtual loopback this is a same-origin /vnet/<port>/ URL, which netscrape's DirectLoader already claims for NATIVE rendering — so the docs render with no visor running, no transport in the path, and the reader can keep a terminal beside them.
It emits HTML, not markdown. Browsers do not render markdown — a native `skywire doc serve` is meant to be opened in an ordinary browser, and making netscrape grow a private content type would make these docs readable only inside skywire.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var RootCmd = &cobra.Command{ Use: "doc", Short: "Regenerate docs/skywire/ from the live cobra tree", Hidden: true, Long: `Walk the cobra command tree rooted at the skywire binary and emit one markdown page per command into the output directory, mirroring the command hierarchy as nested directories. Replaces the hand- maintained cmd/{skywire,skywire-cli,...}/README.md files which had drifted and leaked private data. Run from the repo root so the default --out path resolves: skywire doc # writes docs/skywire/... skywire doc --out /tmp/docs # alternate output root skywire doc --dry-run # list files, don't write skywire doc --capture # also embed live state output # for allowlisted commands`, SilenceErrors: true, SilenceUsage: true, DisableSuggestions: true, DisableFlagsInUseLine: true, Run: func(cmd *cobra.Command, _ []string) { initBuildInfoReplacements() root := cmd.Root() var pages []page collect(root, []string{}, &pages) if dryRun { for _, p := range pages { cmdutil.Println(p.path()) } return } for _, p := range pages { full := filepath.Join(outDir, p.path()) if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil { cmdutil.Eprintf("doc: mkdir %s: %v\n", filepath.Dir(full), err) cmdutil.Exit(1) } f, err := os.Create(full) if err != nil { cmdutil.Eprintf("doc: create %s: %v\n", full, err) cmdutil.Exit(1) } if err := render(f, p); err != nil { _ = f.Close() cmdutil.Eprintf("doc: render %s: %v\n", full, err) cmdutil.Exit(1) } _ = f.Close() } cmdutil.Printf("doc: wrote %d markdown files under %s\n", len(pages), outDir) }, }
RootCmd is mounted by cmd/skywire/commands/root.go. Hidden — users who run `make generate` (or who know the command exists) will see it in --help with `--all` flag, but it's not part of the published CLI.
Functions ¶
func Handler ¶
Handler is docHandler for callers outside this package: the site this command serves, built against the command tree given.
It exists so the link check can run where the REAL tree is assembled. Prose links into the generated reference ("../skywire/cli/config/README.md") are resolved against that tree, so a test holding only a stub root cannot tell a dead link from a command it was never given — and this package cannot import the root itself, which imports this one.
func SiteChrome ¶
SiteChrome is siteChrome for the link check, which lives in the package that assembles the command tree.
Types ¶
This section is empty.
Source Files