collateral

Documentation

Index

• Variables
• func CobraCommand(root *cobra.Command, meta Metadata) *cobra.Command
• func DefaultSelectEnvFn(_ env.Var) bool
• func DefaultSelectMetricFn(_ monitoring.MetricDefinition) bool
• func EmitCollateral(root *cobra.Command, c *Control) error
• type Control
• type CustomTextFunc
• type Metadata
• type Predicates
• type SelectEnvFn
• type SelectMetricFn

Variables

var CustomTextForCmds = map[string]CustomTextFunc{
	"completion-bash": func(cmd string) string {
		return fmt.Sprintf(`<p>Generate the autocompletion script for the bash shell.</p>
<p>This script depends on the &#39;bash-completion&#39; package.
If it is not installed already, you can install it via your OS&#39;s package manager.</p>
<p>To load completions in your current shell session:</p>
<pre class="language-bash"><code>source &lt;(%s completion bash)</code></pre>
<p>To load completions for every new session, execute once:</p>
<h4>Linux:</h4>
<pre class="language-bash"><code>%s completion bash &gt; /etc/bash_completion.d/%s</code></pre>
<h4>macOS:</h4>
<pre class="language-bash"><code>%s completion bash &gt; /usr/local/etc/bash_completion.d/%s</code></pre>
<p>You will need to start a new shell for this setup to take effect.</p>`, cmd, cmd, cmd, cmd, cmd)
	},

	"completion-fish": func(cmd string) string {
		return fmt.Sprintf(`<p>Generate the autocompletion script for the fish shell.</p>
<p>To load completions in your current shell session:</p>
<pre class="language-bash"><code>%s completion fish | source</code></pre>
<p>To load completions for every new session, execute once:</p>
<pre class="language-bash"><code>%s completion bash &gt; ~/.config/fish/completions/%s.fish</code></pre>
<p>You will need to start a new shell for this setup to take effect.</p>`, cmd, cmd, cmd)
	},

	"completion-powershell": func(cmd string) string {
		return fmt.Sprintf(`<p>Generate the autocompletion script for PowerShell.</p>
<p>To load completions in your current shell session:</p>
<pre class="language-bash"><code>%s completion powershell | Out-String | Invoke-Expression</code></pre>
<p>To load completions for every new session, add the output of the above command to your powershell profile.</p>`, cmd)
	},

	"completion-zsh": func(cmd string) string {
		return fmt.Sprintf(`<p>Generate the autocompletion script for the zsh shell.</p>
	<p>If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:</p>
	<pre class="language-bash"><code>echo &#34;autoload -U compinit; compinit&#34; &gt;&gt; ~/.zshrc</code></pre>
	<p>To load completions in your current shell session:</p>
	<pre class="language-bash"><code>source &lt;(%s completion zsh)</code></pre>
	<p>To load completions for every new session, execute once:</p>
	<h4>Linux:</h4>
	<pre class="language-bash"><code>%s completion zsh &gt; &#34;${fpath[1]}/_%s&#34;</code></pre>
	<h4>macOS:</h4>
	<pre class="language-bash"><code>%s completion zsh &gt; $(brew --prefix)/share/zsh/site-functions/_%s</code></pre>
	<p>You will need to start a new shell for this setup to take effect.</p>`, cmd, cmd, cmd, cmd, cmd)
	},
}

Functions

func CobraCommand

func CobraCommand(root *cobra.Command, meta Metadata) *cobra.Command

CobraCommand returns a Cobra command used to output a tool's collateral files (markdown docs, bash completion & man pages) The root argument must be the root command for the tool.

func DefaultSelectEnvFn

func DefaultSelectEnvFn(_ env.Var) bool

DefaultSelectEnvFn is used to select all environment variables.

func DefaultSelectMetricFn

func DefaultSelectMetricFn(_ monitoring.MetricDefinition) bool

DefaultSelectMetricFn is used to select all metrics.

func EmitCollateral

func EmitCollateral(root *cobra.Command, c *Control) error

EmitCollateral produces a set of collateral files for a CLI command. You can select to emit markdown to describe a command's function, man pages, YAML descriptions, and bash completion files.

Types

type Control

type Control struct {
	// OutputDir specifies the directory to output the collateral files
	OutputDir string

	// EmitManPages controls whether to produce man pages.
	EmitManPages bool

	// EmitYAML controls whether to produce YAML files.
	EmitYAML bool

	// EmitBashCompletion controls whether to produce bash completion files.
	EmitBashCompletion bool

	// EmitZshCompletion controls whether to produce zsh completion files.
	EmitZshCompletion bool

	// EmitMarkdown controls whether to produce markdown documentation files.
	EmitMarkdown bool

	// EmitHTMLFragmentWithFrontMatter controls whether to produce HTML fragments with Jekyll/Hugo front matter.
	EmitHTMLFragmentWithFrontMatter bool

	// ManPageInfo provides extra information necessary when emitting man pages.
	ManPageInfo doc.GenManHeader

	// Predicates to use to filter environment variables and metrics. If not set, all items will be selected.
	Predicates Predicates
}

Control determines the behavior of the EmitCollateral function

type CustomTextFunc

type CustomTextFunc func(cmd string) string

type Metadata

type Metadata struct {
	Title   string
	Section string
	Manual  string
}

type Predicates

type Predicates struct {
	SelectEnv    SelectEnvFn
	SelectMetric SelectMetricFn
}

Predicates are a set of predicates to apply when generating collaterals.

type SelectEnvFn

type SelectEnvFn func(env.Var) bool

SelectEnvFn is a predicate function for selecting environment variables when generating collateral documents.

type SelectMetricFn

type SelectMetricFn func(monitoring.MetricDefinition) bool

SelectMetricFn is a predicate function for selecting metrics when generating collateral documents.