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) AtVersion(v string) FieldSpec
  • func (f FieldSpec) HasAnnotatedOptions(options ...string) FieldSpec
  • func (f FieldSpec) HasDefault(v interface{}) FieldSpec
  • func (f FieldSpec) HasOptions(options ...string) FieldSpec
  • func (f FieldSpec) HasType(t FieldType) 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
  • func (f FieldSpecs) RemoveDeprecated(s config.Sanitised)
• type FieldType
  • func GetFieldType(v interface{}) FieldType
• type Status

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

	// The status of the component.
	Status Status

	// 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

	// A summary of each field in the component configuration.
	Fields FieldSpecs

	// Version is the Benthos version this component was introduced.
	Version string
}

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

	// Default value of the field. If left nil the docs generator will attempt
	// to infer the default value from an example config.
	Default interface{}

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

	// 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{}

	// AnnotatedOptions for this field. Each option should have a summary.
	AnnotatedOptions [][2]string

	// Options for this field.
	Options []string

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

	// Version lists an explicit Benthos release where this fields behaviour was last modified.
	Version string
}

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) AtVersion

func (f FieldSpec) AtVersion(v string) FieldSpec

AtVersion specifies the version at which this fields behaviour was last modified.

func (FieldSpec) HasAnnotatedOptions

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

HasAnnotatedOptions returns a new FieldSpec that specifies a specific list of annotated options. Either

func (FieldSpec) HasDefault

func (f FieldSpec) HasDefault(v interface{}) FieldSpec

HasDefault returns a new FieldSpec that specifies a default value.

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(t FieldType) 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.

func (FieldSpecs) RemoveDeprecated

func (f FieldSpecs) RemoveDeprecated(s config.Sanitised)

RemoveDeprecated fields from a sanitized config.

type FieldType

type FieldType string

FieldType represents a field type.

var (
	FieldString  FieldType = "string"
	FieldNumber  FieldType = "number"
	FieldBool    FieldType = "bool"
	FieldArray   FieldType = "array"
	FieldObject  FieldType = "object"
	FieldUnknown FieldType = "unknown"
)

ValueType variants.

func GetFieldType

func GetFieldType(v interface{}) FieldType

GetFieldType attempts to extract a field type from a general value.

type Status

type Status string

Status of a component.

var (
	StatusStable       Status = "stable"
	StatusBeta         Status = "beta"
	StatusExperimental Status = "experimental"
	StatusDeprecated   Status = "deprecated"
)

Component statuses.