Documentation
¶
Overview ¶
Package docs provides a reusable cobra command group that generates a markdown CLI reference and a clicky-ui surface catalog from a CLI's command tree, as one markdown file per high-level command controller.
It mirrors the rpc.NewOpenAPICommand / mcp.NewCommand factory pattern and is wired into a host CLI via extensions.CobraExtensions(root).DocsCommand().
Index ¶
- func NewCommand() *cobra.Command
- func NewCommandWithConfig(cfg *DocsConfig) *cobra.Command
- func RenderCLIReference(m *Model) string
- func RenderController(ctrl ControllerDoc) string
- func RenderSingleFile(m *Model, format string) (string, error)
- func RenderUISurfaces(m *Model) string
- type CommandDoc
- type ControllerDoc
- type DocsConfig
- type FlagDoc
- type Model
- type Page
- type ParameterDoc
- type ScaffoldResult
- type SurfaceDoc
- type WriteAction
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewCommand ¶
NewCommand creates the docs command group with default configuration.
func NewCommandWithConfig ¶
func NewCommandWithConfig(cfg *DocsConfig) *cobra.Command
NewCommandWithConfig creates the docs command group. cfg supplies optional host defaults (title, intro, excluded commands, controller depth).
func RenderCLIReference ¶
RenderCLIReference produces the markdown CLI reference body (no frontmatter). It documents every controller in order, each as a section.
func RenderController ¶
func RenderController(ctrl ControllerDoc) string
RenderController produces the markdown body for a single controller's page (no frontmatter): the controller summary followed by each of its commands.
func RenderSingleFile ¶
RenderSingleFile renders the whole model to one document in the requested format. "markdown" (default) concatenates the CLI reference and UI catalog; "json"/"yaml" emit the structured Model via clicky's FormatManager. Other formats fail loudly — prose markdown is not converted to html/pdf here.
func RenderUISurfaces ¶
RenderUISurfaces produces the markdown clicky-ui surface catalog body (no frontmatter). It documents, per operation: the surface entity + verb, the HTTP endpoint + CLI command the UI invokes, lookup support, and each parameter's UI-widget role.
Types ¶
type CommandDoc ¶
type CommandDoc struct {
Path string `json:"path" yaml:"path"` // e.g. "stack create"
Use string `json:"use" yaml:"use"` // raw cobra Use string
Short string `json:"short" yaml:"short"` // one-line summary
Long string `json:"long" yaml:"long"` // full description
Example string `json:"example" yaml:"example"` // example block
Aliases []string `json:"aliases" yaml:"aliases"` // command aliases
Flags []FlagDoc `json:"flags" yaml:"flags"`
}
CommandDoc documents a single runnable command for the CLI reference.
type ControllerDoc ¶
type ControllerDoc struct {
Name string `json:"name" yaml:"name"` // controller name, e.g. "stack"
Short string `json:"short" yaml:"short"` // controller one-line summary
Long string `json:"long" yaml:"long"` // controller full description
Commands []CommandDoc `json:"commands" yaml:"commands"` // commands within the depth limit
}
ControllerDoc groups the commands of one high-level command controller — a direct child of the root — into a single documentation unit (one page). A top-level leaf command (no subcommands) is its own controller.
type DocsConfig ¶
type DocsConfig struct {
// Title is the docs-site title. Defaults to the root command's name.
Title string
// Description is the intro/landing-page blurb. Defaults to the root
// command's Long (or Short) text.
Description string
// Exclude lists command paths (space-delimited, e.g. "admin secret") that
// should be omitted from the generated CLI reference and UI catalog.
Exclude []string
// Depth limits how many command levels below each high-level controller
// (direct child of root) are included in that controller's page. Depth 1
// (the default) includes the controller and its direct subcommands; depth 2
// descends one level further. Depth 0 uses the default; negative values mean
// unlimited (the whole subtree).
Depth int
}
DocsConfig configures the docs command group. All fields are optional; unset values fall back to metadata derived from the root cobra command.
type FlagDoc ¶
type FlagDoc struct {
Name string `json:"name" yaml:"name"`
Shorthand string `json:"shorthand" yaml:"shorthand"`
Type string `json:"type" yaml:"type"`
Default interface{} `json:"default,omitempty" yaml:"default,omitempty"`
Required bool `json:"required" yaml:"required"`
Usage string `json:"usage" yaml:"usage"`
}
FlagDoc documents a single flag.
type Model ¶
type Model struct {
Title string `json:"title" yaml:"title"`
Description string `json:"description" yaml:"description"`
Version string `json:"version" yaml:"version"`
Controllers []ControllerDoc `json:"controllers" yaml:"controllers"`
Commands []CommandDoc `json:"commands" yaml:"commands"`
Surfaces []SurfaceDoc `json:"surfaces" yaml:"surfaces"`
}
Model is the structured docs model assembled from a CLI's command tree. It is the single source for every output: CLI reference, UI catalog, and the json/yaml structured dumps.
func BuildModel ¶
func BuildModel(root *cobra.Command, cfg *DocsConfig) (*Model, error)
BuildModel converts the root cobra command into a Model using rpc.Converter for operation metadata (paths, verbs, parameter roles) and walking the command tree directly for the CLI reference.
type Page ¶
type Page struct {
Key string // logical key + filename stem: "index", "stack", "ui-surfaces", ...
Title string
Description string
Body string // markdown body
Generated bool // regenerated every run (true) vs write-once starter (false)
}
Page is a logical docs page produced by the generator. Each page is written as a plain markdown file (<Key>.md) directly under the output directory.
type ParameterDoc ¶
type ParameterDoc struct {
Name string `json:"name" yaml:"name"`
Type string `json:"type" yaml:"type"`
Role string `json:"role,omitempty" yaml:"role,omitempty"` // filter/limit/offset/time-from/time-to
Required bool `json:"required" yaml:"required"`
Default interface{} `json:"default,omitempty" yaml:"default,omitempty"`
In string `json:"in" yaml:"in"` // query/path/body
}
ParameterDoc documents a single UI parameter and its widget role.
type ScaffoldResult ¶
type ScaffoldResult struct {
Dir string
Actions []WriteAction
}
ScaffoldResult is the outcome of writing a docs site, for reporting.
func Scaffold ¶
func Scaffold(m *Model, dir string, force bool) (*ScaffoldResult, error)
Scaffold writes the model's pages as flat markdown files directly under dir, applying the two-tier policy: Generated pages are always (re)written; starter pages are written only when absent, unless force is set. Returns a per-file report so the caller can show exactly what was written vs. skipped (no silent skips).
type SurfaceDoc ¶
type SurfaceDoc struct {
Command string `json:"command" yaml:"command"` // CLI command path
Entity string `json:"entity" yaml:"entity"` // entity name
Verb string `json:"verb" yaml:"verb"` // list/get/create/update/delete/action
Method string `json:"method" yaml:"method"` // HTTP method
Path string `json:"path" yaml:"path"` // /api/v1/...
Lookup bool `json:"lookup" yaml:"lookup"` // SupportsLookup
Parameters []ParameterDoc `json:"parameters" yaml:"parameters"`
}
SurfaceDoc documents a clicky-ui operation surface: the entity/verb mapping, its UI-role parameters, lookup support, and the HTTP endpoint + CLI command the UI uses to invoke it.
type WriteAction ¶
type WriteAction struct {
Path string // path relative to the output directory
Status string // "written", "regenerated", or "skipped"
Skipped bool
}
WriteAction records what happened to one file during scaffolding.
Source Files