docs

Documentation

Overview

Package docs provides documentation generation for Cobra commands in multiple formats including Markdown, man pages, YAML, and reStructuredText.

Index

• func EscapeMDXProse(s string) string
• func GenConfigDoc(w io.Writer, tmplContent string) error
• func GenMan(cmd *cobra.Command, header *GenManHeader, w io.Writer) error
• func GenManTree(cmd *cobra.Command, dir string) error
• func GenManTreeFromOpts(cmd *cobra.Command, opts GenManTreeOptions) error
• func GenMarkdown(cmd *cobra.Command, w io.Writer) error
• func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) string) error
• func GenMarkdownTree(cmd *cobra.Command, dir string) error
• func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) error
• func GenMarkdownTreeWebsite(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) error
• func GenMarkdownWebsite(cmd *cobra.Command, w io.Writer, linkHandler func(string) string) error
• func GenReST(cmd *cobra.Command, w io.Writer) error
• func GenReSTCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) string) error
• func GenReSTTree(cmd *cobra.Command, dir string) error
• func GenReSTTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) error
• func GenYaml(cmd *cobra.Command, w io.Writer) error
• func GenYamlCustom(cmd *cobra.Command, w io.Writer, customizer func(*CommandDoc)) error
• func GenYamlTree(cmd *cobra.Command, dir string) error
• func GenYamlTreeCustom(cmd *cobra.Command, dir string, filenameFunc func(*cobra.Command) string) error
• type CommandDoc
• type ConfigDocData
• type ConfigField
• type ConfigGroup
• type ConfigSection
• type GenManHeader
• type GenManTreeOptions
• type OptionDoc

Functions

func EscapeMDXProse

func EscapeMDXProse(s string) string

EscapeMDXProse wraps bare <word> angle-bracket placeholders in backticks so MDX parsers treat them as inline code rather than JSX tags. Text already inside backticks is left unchanged.

func GenConfigDoc

func GenConfigDoc(w io.Writer, tmplContent string) error

GenConfigDoc renders the configuration documentation template to w using schema metadata from the Project and Settings types.

func GenMan

func GenMan(cmd *cobra.Command, header *GenManHeader, w io.Writer) error

GenMan generates a man page for a single command.

func GenManTree

func GenManTree(cmd *cobra.Command, dir string) error

GenManTree generates man pages for cmd and all subcommands. Man pages are written to the specified directory.

func GenManTreeFromOpts

func GenManTreeFromOpts(cmd *cobra.Command, opts GenManTreeOptions) error

GenManTreeFromOpts generates man pages with custom options.

func GenMarkdown

func GenMarkdown(cmd *cobra.Command, w io.Writer) error

GenMarkdown generates markdown documentation for a single command.

func GenMarkdownCustom

func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) string) error

GenMarkdownCustom generates markdown documentation with a custom link handler.

func GenMarkdownTree

func GenMarkdownTree(cmd *cobra.Command, dir string) error

GenMarkdownTree generates markdown documentation for a command and all its subcommands. Files are created in the specified directory using the command path as filename.

func GenMarkdownTreeCustom

func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) error

GenMarkdownTreeCustom generates markdown documentation with custom file prepender and link handler. The filePrepender is called with each filename to prepend content (e.g., front matter). The linkHandler transforms command names to links (e.g., adding .md extension).

func GenMarkdownTreeWebsite

func GenMarkdownTreeWebsite(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) error

GenMarkdownTreeWebsite generates MDX-safe markdown documentation for a command tree. It wraps bare <word> placeholders in backticks within prose sections while leaving fenced code blocks untouched.

func GenMarkdownWebsite

func GenMarkdownWebsite(cmd *cobra.Command, w io.Writer, linkHandler func(string) string) error

GenMarkdownWebsite generates MDX-safe markdown for a single command.

func GenReST

func GenReST(cmd *cobra.Command, w io.Writer) error

GenReST generates reStructuredText documentation for a single command.

func GenReSTCustom

func GenReSTCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) string) error

GenReSTCustom generates reStructuredText documentation with a custom link handler.

func GenReSTTree

func GenReSTTree(cmd *cobra.Command, dir string) error

GenReSTTree generates reStructuredText documentation for a command and all its subcommands. Files are created in the specified directory using the command path as filename.

func GenReSTTreeCustom

func GenReSTTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) error

GenReSTTreeCustom generates reStructuredText documentation with custom file prepender and link handler. The filePrepender is called with each filename to prepend content (e.g., directives). The linkHandler transforms command names to RST links.

func GenYaml

func GenYaml(cmd *cobra.Command, w io.Writer) error

GenYaml generates YAML documentation for a single command.

func GenYamlCustom

func GenYamlCustom(cmd *cobra.Command, w io.Writer, customizer func(*CommandDoc)) error

GenYamlCustom generates YAML documentation with custom processing.

func GenYamlTree

func GenYamlTree(cmd *cobra.Command, dir string) error

GenYamlTree generates YAML documentation for a command and all its subcommands. Each command is written to a separate file.

func GenYamlTreeCustom

func GenYamlTreeCustom(cmd *cobra.Command, dir string, filenameFunc func(*cobra.Command) string) error

GenYamlTreeCustom generates YAML documentation with a custom filename function.

Types

type CommandDoc

type CommandDoc struct {
	Name             string       `yaml:"name"`
	Synopsis         string       `yaml:"synopsis,omitempty"`
	Description      string       `yaml:"description,omitempty"`
	Usage            string       `yaml:"usage,omitempty"`
	Aliases          []string     `yaml:"aliases,omitempty"`
	Options          []OptionDoc  `yaml:"options,omitempty"`
	InheritedOptions []OptionDoc  `yaml:"inherited_options,omitempty"`
	Commands         []CommandDoc `yaml:"commands,omitempty"`
	Examples         string       `yaml:"examples,omitempty"`
	SeeAlso          []string     `yaml:"see_also,omitempty"`
}

CommandDoc represents YAML documentation structure for a command.

type ConfigDocData

type ConfigDocData struct {
	ProjectSections  []ConfigSection
	SettingsSections []ConfigSection
}

ConfigDocData is the full template data for configuration.mdx.

type ConfigField

type ConfigField struct {
	Path        string // Dotted YAML path (e.g. "build.image")
	Key         string // Leaf key name (e.g. "image")
	Label       string
	Description string
	Type        string // Human-readable type (e.g. "string", "boolean", "string list")
	Default     string
	Required    bool
}

ConfigField is a single leaf field for template rendering.

type ConfigGroup

type ConfigGroup struct {
	Key    string        // YAML key relative to section (e.g. "instructions")
	Path   string        // Full dotted path (e.g. "build.instructions")
	Fields []ConfigField // Leaf fields in this group
}

ConfigGroup is a nested group of fields under a section (e.g. instructions, inject).

type ConfigSection

type ConfigSection struct {
	Key    string        // YAML key (e.g. "build")
	Fields []ConfigField // Leaf fields in this section
	Groups []ConfigGroup // Sub-groups (e.g. "build.instructions", "build.inject")
}

ConfigSection is a top-level config section (build, agent, security, etc.) passed to the template.

type GenManHeader

type GenManHeader struct {
	Title   string
	Section string
	Date    *time.Time
	Source  string
	Manual  string
}

GenManHeader contains man page metadata

type GenManTreeOptions

type GenManTreeOptions struct {
	Path             string
	CommandSeparator string
	Header           *GenManHeader
}

GenManTreeOptions configures man page generation

type OptionDoc

type OptionDoc struct {
	Name         string `yaml:"name"`
	Shorthand    string `yaml:"shorthand,omitempty"`
	DefaultValue string `yaml:"default_value,omitempty"`
	Usage        string `yaml:"usage"`
	Type         string `yaml:"type,omitempty"`
}

OptionDoc represents YAML documentation for a command flag.