embedutil

Documentation

Overview

Package embedutil provides utility functions for embedding documents in a Go binary and producing those documents in various formats

Index

• func GenMarkdownCustom(cmd *cobra.Command, w io.Writer) error
• func SetUsageFormat(opts cobrautil.UsageFormatOptions)
• type Category
  • func NewCategory(key, title, manpagePrefix string, manpageExt int8, docs ...*Document) *Category
• type DocType
• type Document
  • func LoadJSONSchema(key, title, name string, filesys fs.FS) *Document
  • func LoadJSONSchemaBytes(key, title, name string, data []byte) *Document
  • func LoadJSONSchemaString(key, title, name, data string) *Document
  • func LoadMarkdown(key, title, name string, filesys fs.FS) *Document
  • func LoadMarkdownBytes(key, title, name string, data []byte) *Document
  • func LoadMarkdownString(key, title, name string, data string) *Document
  • func (doc *Document) ManpageExt() string
  • func (doc *Document) Render(format Format) ([]byte, error)
  • func (doc *Document) RenderedName(format Format) string
• type Documentation
  • func (docs *Documentation) FindDocument(key string) *Document
  • func (docs *Documentation) Index(outputDir string, opts *Options) ([]byte, error)
  • func (docs *Documentation) Write(ctx context.Context, outputDir string, opts *Options) error
• type Encoding
• type Format
  • func (f Format) IndexFile() string
• type Options
  • func (opts *Options) TypeRequested(checkType DocType) bool

Functions

func GenMarkdownCustom

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

GenMarkdownCustom creates custom Markdown output. github.com/spf13/cobra/blob/main/doc/md_docs.go

func SetUsageFormat

func SetUsageFormat(opts cobrautil.UsageFormatOptions)

SetUsageFormat sets common formatting for usage documentation.

Types

type Category

type Category struct {
	Key   string      // Key name for the category in kebab-case
	Title string      // Readable name for the category (can include spaces)
	Docs  []*Document // List of documents contained in the category
}

Category is used to group documents

func NewCategory

func NewCategory(key, title, manpagePrefix string, manpageExt int8, docs ...*Document) *Category

NewCategory initializes a new Category object

type DocType

type DocType string

DocType represents an overarching area of documentation

const (
	// TypeAll represents all types
	TypeAll DocType = "all"

	// TypeGeneral represents general documentation
	TypeGeneral DocType = "general"

	// TypeCommands represents CLI command documentation
	TypeCommands DocType = "commands"

	// TypeSchemas represents API schema documentation
	TypeSchemas DocType = "schemas"
)

type Document

type Document struct {
	Key   string // Key name for the file in kebab-case
	Title string // Human-readable title for the document

	Contents []byte // Contents of the document
	// contains filtered or unexported fields
}

Document represents an embedded document

func LoadJSONSchema

func LoadJSONSchema(key, title, name string, filesys fs.FS) *Document

LoadJSONSchema loads a JSON Schema definition into a Document name must be the path to the document in filesys

func LoadJSONSchemaBytes

func LoadJSONSchemaBytes(key, title, name string, data []byte) *Document

LoadJSONSchemaBytes loads JSON Schema definition bytes into a Document

func LoadJSONSchemaString

func LoadJSONSchemaString(key, title, name, data string) *Document

LoadJSONSchemaString loads a JSON Schema definition string into a Document

func LoadMarkdown

func LoadMarkdown(key, title, name string, filesys fs.FS) *Document

LoadMarkdown loads a markdown file into a Document name must be the path to the document in filesys

func LoadMarkdownBytes

func LoadMarkdownBytes(key, title, name string, data []byte) *Document

LoadMarkdownBytes loads markdown bytes into a Document

func LoadMarkdownString

func LoadMarkdownString(key, title, name string, data string) *Document

LoadMarkdownString loads a markdown string into a Document

func (*Document) ManpageExt

func (doc *Document) ManpageExt() string

ManpageExt produces the extension to be used for this document when represented as a manpage

func (*Document) Render

func (doc *Document) Render(format Format) ([]byte, error)

Render produces the document's content in the requested format

func (*Document) RenderedName

func (doc *Document) RenderedName(format Format) string

RenderedName produces the output file name of a document based on the format

type Documentation

type Documentation struct {
	// Overall title for the documentation
	Title string

	// Root cobra.Command
	Command *cobra.Command

	// Categories stores a list of documentation sub-categories,
	// allowing organization of generated documentation
	// Ordering is obeyed in the indexer
	Categories []*Category
}

Documentation configures how different genres of embedded documentation will be generated

func (*Documentation) FindDocument

func (docs *Documentation) FindDocument(key string) *Document

FindDocument returns the Document with the requested key

func (*Documentation) Index

func (docs *Documentation) Index(outputDir string, opts *Options) ([]byte, error)

Index creates an index file for the documentation in the requested format

func (*Documentation) Write

func (docs *Documentation) Write(ctx context.Context, outputDir string, opts *Options) error

Write outputs all embedded documentation in the outputDir

type Encoding

type Encoding string

Encoding represents an embedded document's encoding

const (
	// EncodingMarkdown represents a Markdown-encoded document
	EncodingMarkdown Encoding = "md"

	// EncodingManpage represents a manpage document
	EncodingManpage Encoding = "man"

	// EncodingJSONSchema represents a JSON-encoded JSON Schema definition
	EncodingJSONSchema Encoding = "jsonschema"

	// EncodingCRD represents a YAML-encoded CustomResourceDefinition
	EncodingCRD Encoding = "crd"

	// EncodingHTML represents an HTML document
	EncodingHTML Encoding = "html"

	// EncodingRaw represents a raw document
	EncodingRaw Encoding = "raw"
)

type Format

type Format string

Format represents the output format for embedded documents

const (
	// Markdown represents Markdown output
	Markdown Format = "md"

	// HTML represents HTML output
	HTML Format = "html"

	// Manpage represents manpage output
	Manpage Format = "man"
)

func (Format) IndexFile

func (f Format) IndexFile() string

IndexFile returns the index file name corresponding to the format

type Options

type Options struct {
	Format Format    // Output format
	Types  []DocType // Documentation types to generate
	Index  bool      // Generate a documentation index file (format-dependent)
	Flat   bool      // Generate documentation in a flat directory structure
}

Options stores configuration for rendering embedded documentation

func (*Options) TypeRequested

func (opts *Options) TypeRequested(checkType DocType) bool

TypeRequested checks if a type was requested from the options