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`. A session leases its bundle (HoldBundle), so another build's eviction never removes the pages the session's prompt names. 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 HoldBundle(configRoot string) (release func())
- 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 HoldBundle ¶
func HoldBundle(configRoot string) (release func())
HoldBundle leases this build's bundle in configRoot for as long as the process lives, so another build's eviction does not remove the pages a running session's prompt names. It does nothing when the bundle is not complete on disk, and nothing is written. A session does not call the returned release until it exits (the exit path calls it just before the exit record counts descriptors) and tests call it. The bundle is read again once leased, so an eviction between the check and the lease is not mistaken for a held bundle. pig additive (D22): Pi's package docs stay where they are for as long as Pi runs; PiG's bundle lives in a directory that other builds evict.
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.