docs

Documentation

Overview

Package docs provides useful functions for creating documentation from Benthos components

Index

• func BloblangFunctionsMarkdown() ([]byte, error)
• func BloblangMethodsMarkdown() ([]byte, error)
• type AnnotatedExample
• type ComponentSpec
  • func (c *ComponentSpec) AsMarkdown(nest bool, fullConfigExample interface{}) ([]byte, error)
• type FieldInterpolation
• type FieldSpec
  • func FieldAdvanced(name, description string, examples ...interface{}) FieldSpec
  • func FieldCommon(name, description string, examples ...interface{}) FieldSpec
  • func FieldDeprecated(name string) FieldSpec
  • func (f FieldSpec) HasOptions(options ...string) FieldSpec
  • func (f FieldSpec) HasType(typeStr string) FieldSpec
  • func (f FieldSpec) SupportsInterpolation(batchWide bool) FieldSpec
  • func (f FieldSpec) WithChildren(children ...FieldSpec) FieldSpec
• type FieldSpecs
  • func (f FieldSpecs) Add(specs ...FieldSpec) FieldSpecs
  • func (f FieldSpecs) ConfigAdvanced(config interface{}) (interface{}, error)
  • func (f FieldSpecs) ConfigCommon(config interface{}) (interface{}, error)
  • func (f FieldSpecs) Merge(specs FieldSpecs) FieldSpecs

Functions

func BloblangFunctionsMarkdown

func BloblangFunctionsMarkdown() ([]byte, error)

BloblangFunctionsMarkdown returns a markdown document for all Bloblang functions.

func BloblangMethodsMarkdown

func BloblangMethodsMarkdown() ([]byte, error)

BloblangMethodsMarkdown returns a markdown document for all Bloblang methods.

Types

type AnnotatedExample

type AnnotatedExample struct {
	// A title for the example.
	Title string

	// Summary of the example.
	Summary string

	// A config snippet to show.
	Config string
}

AnnotatedExample is an isolated example for a component.

type ComponentSpec

type ComponentSpec struct {
	// Name of the component
	Name string

	// Type of the component (input, output, etc)
	Type string

	// Summary of the component (in markdown, must be short).
	Summary string

	// Description of the component (in markdown).
	Description string

	// Categories that describe the purpose of the component.
	Categories []string

	// Footnotes of the component (in markdown).
	Footnotes string

	// Examples demonstrating use cases for the component.
	Examples []AnnotatedExample

	// Whether the component is beta.
	Beta bool

	// Whether the component is now deprecated.
	Deprecated bool

	Fields FieldSpecs
}

ComponentSpec describes a Benthos component.

func (*ComponentSpec) AsMarkdown

func (c *ComponentSpec) AsMarkdown(nest bool, fullConfigExample interface{}) ([]byte, error)

AsMarkdown renders the spec of a component, along with a full configuration example, into a markdown document.

type FieldInterpolation

type FieldInterpolation int

FieldInterpolation represents a type of interpolation supported by a field.

const (
	FieldInterpolationNone FieldInterpolation = iota
	FieldInterpolationBatchWide
	FieldInterpolationIndividual
)

Interpolation types.

type FieldSpec

type FieldSpec struct {
	// Name of the field (as it appears in config).
	Name string

	// Description of the field purpose (in markdown).
	Description string

	// Advanced is true for optional fields that will not be present in most
	// configs.
	Advanced bool

	// Deprecated is true for fields that are deprecated and only exist for
	// backwards compatibility reasons.
	Deprecated bool

	// Type of the field. This is optional and doesn't prevent documentation for
	// a field.
	Type string

	// Interpolation indicates the type of interpolation that this field
	// supports.
	Interpolation FieldInterpolation

	// Examples is a slice of optional example values for a field.
	Examples []interface{}

	// Options for this field.
	Options []string

	// Children fields of this field (it must be an object).
	Children FieldSpecs
}

FieldSpec describes a component config field.

func FieldAdvanced

func FieldAdvanced(name, description string, examples ...interface{}) FieldSpec

FieldAdvanced returns a field spec for an advanced field.

func FieldCommon

func FieldCommon(name, description string, examples ...interface{}) FieldSpec

FieldCommon returns a field spec for a common field.

func FieldDeprecated

func FieldDeprecated(name string) FieldSpec

FieldDeprecated returns a field spec for a deprecated field.

func (FieldSpec) HasOptions

func (f FieldSpec) HasOptions(options ...string) FieldSpec

HasOptions returns a new FieldSpec that specifies a specific list of options.

func (FieldSpec) HasType

func (f FieldSpec) HasType(typeStr string) FieldSpec

HasType returns a new FieldSpec that specifies a specific type.

func (FieldSpec) SupportsInterpolation

func (f FieldSpec) SupportsInterpolation(batchWide bool) FieldSpec

SupportsInterpolation returns a new FieldSpec that specifies whether it supports function interpolation (batch wide or not).

func (FieldSpec) WithChildren

func (f FieldSpec) WithChildren(children ...FieldSpec) FieldSpec

WithChildren returns a new FieldSpec that has child fields.

type FieldSpecs

type FieldSpecs []FieldSpec

FieldSpecs is a slice of field specs for a component.

func (FieldSpecs) Add

func (f FieldSpecs) Add(specs ...FieldSpec) FieldSpecs

Add more field specs.

func (FieldSpecs) ConfigAdvanced

func (f FieldSpecs) ConfigAdvanced(config interface{}) (interface{}, error)

ConfigAdvanced takes a sanitised configuration of a component, a map of field docs, and removes all fields that are deprecated.

func (FieldSpecs) ConfigCommon

func (f FieldSpecs) ConfigCommon(config interface{}) (interface{}, error)

ConfigCommon takes a sanitised configuration of a component, a map of field docs, and removes all fields that aren't common or are deprecated.

func (FieldSpecs) Merge

func (f FieldSpecs) Merge(specs FieldSpecs) FieldSpecs

Merge with another set of FieldSpecs.