Documentation
¶
Overview ¶
Package pigdocs materializes the reference documentation embedded in Stock Pig under the user's config root.
Pig ships as a standalone binary. Unlike upstream Pi, which installs package documentation beside its npm entry point, Pig cannot assume that a source checkout exists. The embedded bundle lets the running agent inspect the exact extension, Package, and Piglet contracts that its binary implements.
Each build writes its bundle to its own content-addressed directory, so PiG builds that share a config root (two installed versions, or stock PiG beside a Piglet Binary) never rewrite each other's docs, and a running session's docs never change under it. Users can also force a sync or read the bundle through `pig docs`. This is stock distribution infrastructure; it does not activate an extension or optional Piglet.
Output layout
~/.pig/docs/
bundle-<hash>/ one build's bundle; <hash> is its content digest
README.md index
commands.md slash commands + CLI verbs
... one page per embedded content/*.md
.pig-docs-digest the full digest, written last
Index ¶
- Constants
- func DocsDir(configRoot string) string
- func EnsureSynced(configRoot string) error
- func List() []string
- func Prepare(configRoot string) (present, pending bool, err error)
- func Read(name string) ([]byte, error)
- func RunCommand(args []string, stdout, stderr io.Writer) int
- func Sync(configRoot string) ([]string, error)
Constants ¶
const (
// SubDir is the docs directory name under the pig config root.
SubDir = "docs"
)
Variables ¶
This section is empty.
Functions ¶
func DocsDir ¶
DocsDir returns the absolute directory of this build's bundle for a given config root.
func EnsureSynced ¶
EnsureSynced is the idempotent startup helper. A complete bundle of this build costs one marker read and, at most hourly, a recorded use time; otherwise it syncs. All errors are returned to the caller; Pig core treats any failure as the bundle being absent.
func List ¶
func List() []string
List returns the embedded doc filenames in stable alphabetical order. It is the canonical source for `pig docs list` and for any caller that needs to enumerate available topics.
func Prepare ¶
Prepare is the startup check that defers the write of the bundle until something can read it. It returns present, whether text may name the bundle, and pending, whether EnsureSynced must run before anything other than PiG reads it. A complete bundle of this build costs one marker read and, at most hourly, a recorded use time; it is present and nothing is pending. Otherwise the bundle is named when the config root lets this process create it, the condition under which EnsureSynced writes it; nothing is written here. pig additive (D22): Pi's package docs exist before it starts; PiG writes its bundle before the first reader instead of at every start.
func Read ¶
Read returns the embedded bytes of a single doc file. Names may be given with or without the .md suffix; ".." and absolute paths are rejected so this is safe to drive from CLI input.
func RunCommand ¶
RunCommand implements the stock pre-session `pig docs` command. It returns -1 when the arguments target another command.
pig docs sync + summary (default) pig docs sync force re-sync embedded docs pig docs path print docs dir pig docs list list available doc files pig docs show <name> print one doc to stdout
Types ¶
This section is empty.