Documentation
¶
Overview ¶
Package gen contains funtions to generate documentation and framework-specific boilerplate code from a valid OpenCLI specification document.
Given a spec.Document, gen can produce:
Documentation — Call Docs to generate Markdown (or other formats) suitable for publishing CLI reference documentation.
CLI code — Call CLI with a target CLIFramework to generate boilerplate code for one of the supported frameworks:
• CobraFramework — github.com/spf13/cobra (Go) • UrfaveCliFramework — github.com/urfave/cli/v3 (Go) • YargsFramework — yargs (Node.js)
Generated code is returned as a map of relative file paths to their contents, ready to be written to disk. All files belong to a single gencli package so no cross-package import paths are required.
Both CLI and Docs support functional options for configuring output format, framework, badges, footers, and other generation parameters.
Package gen contains functions to generate documentation and framework-specific boilerplate code from a valid OpenCLI specification document.
Given a spec.Document, gen can produce:
Documentation — Call Docs to generate Markdown (or other formats) suitable for publishing CLI reference documentation.
CLI code — Call CLI with a target CLIFramework to generate boilerplate code for one of the supported frameworks:
• CobraFramework — github.com/spf13/cobra (Go) • UrfaveCliFramework — github.com/urfave/cli/v3 (Go) • YargsFramework — yargs (Node.js)
Generated code is returned as a map of relative file paths to their contents, ready to be written to disk. All files belong to a single gencli package so no cross-package import paths are required.
Both CLI and Docs support functional options for configuring output format, framework, badges, footers, and other generation parameters.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CLI ¶
CLI generates framework-specific boilerplate code from an OpenCLI document. It returns a map of relative file paths (under gencli/) to their generated content, ready to be written to disk. All files belong to the gencli package.
Example:
files, err := gen.CLI(doc, gen.GenCLIWithFramework(gen.YargsFramework))
if err != nil { return err }
for path, content := range files {
fs.WriteFile(path, content, 0644)
}
func Docs ¶
func Docs(doc *spec.Document, options ...GenDocsOption) ([]byte, error)
Docs generates documentation based on the given OpenCLI document. It delegates to format-specific generators:
- Markdown → genDocsMarkdown (docs_md.go) - HTML_PAGE, HTML_EMBED → genDocsHTML (docs_html.go)
Types ¶
type CLIFramework ¶
type CLIFramework string
CLIFramework is the target framework for CLI code generation.
Use with GenCLIWithFramework to select a supported framework:
files, err := gen.CLI(doc, gen.GenCLIWithFramework(gen.CobraFramework))
const ( // CobraFramework generates code for the github.com/spf13/cobra framework. CobraFramework CLIFramework = "COBRA" // YargsFramework generates code for the yargs Node.js framework. YargsFramework CLIFramework = "YARGS" // UrfaveCliFramework generates code for the github.com/urfave/cli/v3 framework. UrfaveCliFramework CLIFramework = "URFAVECLI" )
func (CLIFramework) IsValid ¶
func (f CLIFramework) IsValid() bool
IsValid reports whether f is a supported CLIFramework.
type DocFormat ¶
type DocFormat string
DocFormat is the output format for generated documentation.
const ( // Markdown generates plain Markdown documentation. Markdown DocFormat = "MARKDOWN" // HTML_PAGE generates a full standalone HTML page. HTML_PAGE DocFormat = "HTML_PAGE" // HTML_EMBED generates a JavaScript bundle that can be embedded in an existing page. HTML_EMBED DocFormat = "HTML_EMBED" // ManPage generates a man page. MAN DocFormat = "MAN" )
type GenCLIOption ¶
type GenCLIOption func(*genCLIOptions)
GenCLIOption is a functional option to configure the CLI function.
func GenCLIWithFramework ¶
func GenCLIWithFramework(f CLIFramework) GenCLIOption
GenCLIWithFramework sets the target CLI framework.
type GenDocsOption ¶
type GenDocsOption func(*genDocsOptions)
GenDocsOption is a functional option to configure the Docs function.
func DocsWithFormat ¶
func DocsWithFormat(format DocFormat) GenDocsOption
DocsWithFormat sets the desired output format of the documentation.
func DocsWithoutBadge ¶
func DocsWithoutBadge() GenDocsOption
DocsWithoutBadge option will remove shields.io badge that indicates compliance with the OpenCLI Spec prepended to markdown documents by default.
func DocsWithoutFooter ¶
func DocsWithoutFooter() GenDocsOption
DocsWithoutFooter option will remove the `generated by OpenCLI` footer appended to the documents by default.
Source Files