Documentation
¶
Overview ¶
Package docs provides a documentation system with two subsystems: a generation engine that parses Cobra command trees into Markdown files with hierarchy-aware index management, and a TUI browser built on Bubbles with split-pane navigation, async search, and AI-powered Q&A via retrieval-augmented generation (RAG).
Documentation is typically embedded in the binary via props.Assets under an assets/docs path, and the feature can be toggled via the DocsCmd feature flag.
Index ¶
- func AskAI(ctx context.Context, p *props.Props, fsys fs.FS, question string, ...) (string, error)
- func GenerateManPage(w io.Writer, cmd *cobra.Command, opts ManOptions) error
- func GenerateManTree(root *cobra.Command, opts ManOptions) error
- func GetAllMarkdownContent(fsys fs.FS) (string, error)
- func ManPagePaths(root *cobra.Command, opts ManOptions) []string
- func ManSource(name string, p *props.Props) string
- func ResolveProvider(p props.ConfigProvider, providerOverride ...string) chat.Provider
- func Serve(ctx context.Context, fsys fs.FS, port int, opts ...ServeOption) error
- type AskDeltaMsg
- type AskFunc
- type AskLogMsg
- type AskResponse
- type AskResultMsg
- type ListItem
- type LogFinishedMsg
- type ManOptions
- type MkDocsConfig
- type Model
- type NavNode
- type Option
- type SearchResult
- type SearchResultMessage
- type ServeOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AskAI ¶
func AskAI(ctx context.Context, p *props.Props, fsys fs.FS, question string, logFn func(string, logger.Level), deltaFn func(string), providerOverride ...string) (string, error)
AskAI queries the AI about the embedded documentation. If the provider supports streaming, deltas are delivered via deltaFn as they arrive. logFn receives status messages. Either callback may be nil.
func GenerateManPage ¶ added in v0.22.0
GenerateManPage renders a single command's roff page to w, applying the same header policy as GenerateManTree (no file is written). It backs the runtime "man" command's stdout preview so a single page and the full tree share one header/auto-gen policy.
func GenerateManTree ¶ added in v0.22.0
func GenerateManTree(root *cobra.Command, opts ManOptions) error
GenerateManTree renders roff man pages for root and all descendants into opts.Dir/man<section>, applying GTB's header policy. It is the single rendering seam shared by "gtb generate man" and the runtime "man" command, so both surfaces produce identical output.
func GetAllMarkdownContent ¶
GetAllMarkdownContent walks the FS and concatenates all .md files.
func ManPagePaths ¶ added in v0.22.0
func ManPagePaths(root *cobra.Command, opts ManOptions) []string
ManPagePaths returns the man-page paths GenerateManTree would write for root and its descendants, in tree order, under opts.Dir/man<section>. It backs the --dry-run preview. It mirrors cobra's availability filter and dashed CommandSeparator, so it must stay in sync with GenerateManTree's GenManTreeOptions (CommandSeparator: "-").
func ManSource ¶ added in v0.22.0
ManSource builds the .TH source footer "<name> <version>" from the running binary's version, falling back to the bare name. It is shared by the build-time "generate man" and runtime "man" commands so both emit an identical footer.
func ResolveProvider ¶
func ResolveProvider(p props.ConfigProvider, providerOverride ...string) chat.Provider
ResolveProvider determines the AI provider to use based on override, config, and defaults.
Types ¶
type AskDeltaMsg ¶
AskDeltaMsg is a Bubble Tea message carrying a streamed text fragment from the AI.
type AskFunc ¶
type AskFunc func(question string, logFn func(string, logger.Level), deltaFn func(string)) (string, error)
AskFunc is the callback signature for AI Q&A. logFn receives status messages; deltaFn receives streamed text fragments as they arrive (may be nil).
type AskResponse ¶
type AskResponse struct {
Answer string `json:"answer" jsonschema:"description=The comprehensive answer to the user's question based on the documentation provided."`
}
AskResponse is the structured response from an AI Q&A query.
type AskResultMsg ¶
AskResultMsg is a Bubble Tea message carrying the AI Q&A response.
type LogFinishedMsg ¶
type LogFinishedMsg struct{}
LogFinishedMsg is a Bubble Tea message signalling that AI log streaming is complete.
type ManOptions ¶ added in v0.22.0
type ManOptions struct {
// Dir is the output base directory; pages are written under Dir/man<section>
// (e.g. man1/<command-path>.1) to match the FHS layout packagers expect.
Dir string
// Title sets the .TH title for every page. When blank, cobra derives a
// per-command title from the command path (e.g. GTB-GENERATE), which is the
// correct man-page convention — leave it blank unless a fixed title is
// required.
Title string
// Section is the man section; defaults to "1" (user commands).
Section string
// Source and Manual populate the .TH header (e.g. "gtb 0.21.0", "GTB
// Manual"). They are always set so the cobra "Auto generated by spf13/cobra"
// placeholder never ships; blank values are defaulted from the root command.
Source string
Manual string
// Date, when nil, omits the auto-generated date trailer
// (DisableAutoGenTag) so output is reproducible; the .TH date still honours
// SOURCE_DATE_EPOCH. When set, the date is stamped into the .TH header.
Date *time.Time
}
ManOptions configures roff man-page generation for a command tree.
type MkDocsConfig ¶
type MkDocsConfig struct {
}
MkDocsConfig is the parsed structure of mkdocs.yml for navigation extraction.
type Model ¶
type Model struct {
// contains filtered or unexported fields
}
Model is the Bubble Tea model for the interactive documentation browser. It manages navigation, content rendering, search, and AI Q&A.
type NavNode ¶
type NavNode struct {
}
NavNode represents a node in the documentation navigation tree.
type Option ¶
type Option func(*Model)
Option is a functional option for configuring the documentation Model.
func WithAskFunc ¶
WithAskFunc configures the AI Q&A callback for the documentation browser.
type SearchResult ¶
SearchResult holds a single search match with context excerpt.
type SearchResultMessage ¶
type SearchResultMessage struct {
Results []SearchResult
Query string
}
SearchResultMessage is a Bubble Tea message carrying search results.
type ServeOption ¶ added in v0.17.0
type ServeOption func(*serveConfig)
ServeOption configures the documentation server started by Serve.
func WithHost ¶ added in v0.17.0
func WithHost(host string) ServeOption
WithHost overrides the interface the documentation server binds to. The default is loopback (127.0.0.1). Pass "0.0.0.0" (or "::") to expose the server on all interfaces — only do this on a trusted network. An empty host falls back to the loopback default.