How to document plugins¶

Background¶

Documentation for each plugin is sourced from a single location - the plugin’s source code - and presented in two locations.

Standard godocs based documentation is targeted at developers interested in writing Gollum plugins or developing Gollum itself and describes implementation-level details of Gollum’s plugin API and internals.
The Plugins chapter of Gollum’s documentation on readthedocs.org describes the built-in plugins’ features and configuration from the viewpoint of an end user or operator.

The readthedocs.org documentation is generated by a custom tool (./docs/generator) that converts the godoc formatted comments into RST. Consequently, plugin source code comments must satisfy the syntax requirements of both godoc and Gollum’s rst_generator.

Syntax¶

Each plugin’s documentation is contained in the comment block immediately preceding the plugin’s Go struct definition with al according to godoc rules. Other comments in the plugin source are ignored by the RST generator.

Single-line comments (“// ….”) are used for inline documentation. For the purpose of this document, the initial “// ” sequences on each line are not part of the comment block; an “empty line” means a line solely consisting of the comment sequence and optional trailing whitespace.

The following types of elements are recognized by the RST generator:

Heading A heading is defined by text that is surrounded by blank lines. If a heading is starting a documentation block, the preceding blank line is omitted. Please note that a heading is only detected as heading by godoc if there is regular text following the blank line after the heading.
Enumeration A “- ” as the first non-space sequence on a line begins an enumeration list item, which continues over zero or more further lines, terminated by a Heading or another enumeration list item. Continuation lines must match the indentation of the beginning line.
Keyed enumeration A colon (“:”) on the first line of an enumeration specifies a keyed enumeration list item. The text between “- ” and “:” defines the item’s key; the rest its contents.
Nested enumerations Enumerations may be nested; each level is indented by a single space. Indentation must begin at 0.

Contents¶

The contents of a documentation block consists of 4 parts:

General description

The heading of this section starts with the name of the plugin followed by its type e.g. “Console consumer”.

The contents of this section should describe what the plugin does, including any special considerations.
Metadata fields

The heading of this secion is “Metadata”.

The contents of this section is an enumeration (of keyed and/or unkeyed elements) of all metadata fields consumed or generated by the plugin.

The RST generatorwill automatically inherit the Metadata sections from plugins embedded by this type, so there is no need to duplicate their documentation in your own plugin. You can, however, override inherited fields’ documentation if needed.

Fields that have specific keys should be documented using keyed enumerations, e.g. “- key: stores the key of the request”.
Configuration parameters

The heading of this secion is “Parameters”.

The contents of this section is a keyed enumeration of configuration parameters recognized by the plugin.

The RST generator will automatically inherit the Parameters sections from plugins embedded by this type, so there is no need to duplicate their documentation in your own plugin. You can, however, override inherited parameters’ documentation if needed.

Default values and units are picked up automatically from struct tags for struct properties that have the ‘config’ and one or both of ‘default’ and ‘metric’ tags.
Configuration Examples

The heading of this section is “Examples”.

This section should contain at least one configuration example and a short description for each example provided.

The example is meant to be a working demonstration of the plugin’s usage, not an exhaustive listing of all possible features and parameters. The user should be able to copy-paste it into a config file as-is. It doesn’t need to be self-contained and should not include any boilerplate configuration for other plugins, with the exception of nested plugins (filters and formatters), which should be contained in the following stub:
```
ExampleConsumer:
  Type: consumer.Console
  Streams: console
  Modulators:
```

Struct Tags¶

The same Go struct tags used by Gollum to parse and set plugin configuration parameters are supported by the RST generator:

config:”<ConfigParameter>” maps this struct property to the <ConfigParameter> parameter
default:”<defval>” specifies <defval> as the parameter’s default value
metric:”<unit>” specifies <unit> as the parameter’s unit

To inherit an embedded struct type’s Metadata and Parameters documentation in your own plugin’s documentation, add the gollumdoc:”embed_type” in the embed instruction.

Structure¶

The general structure of a plugin documentation block looks like this:

// <BLOCK HEADING>
//
// <CHAPTER CONTENTS>
// <CHAPTER CONTENTS>
//
// <CHAPTER HEADING>
//
// <CHAPTER CONTENTS>
// <CHAPTER CONTENTS>
//
// <CHAPTER HEADING>
//
// <CHAPTER CONTENTS>
// <CHAPTER CONTENTS>
//
// Metadata
//
// - <METADATA KEY>: <DESCRIPTION
// DESCRIPTION CONTINUED ...>
// - <METADATA KEY>: <DESCRIPTION>
// - <VARIABLE-NAMED METADATA FIELD
// DESCRIPTION CONTINUED ...>
//
// Parameters
//
// - <PARAMETER NAME>: <PARAMETER DESCRIPTION>
// - <PARAMETER NAME>: <PARAMETER DESCRIPTION
// DESCRIPTION CONTINUED ...>
//  - <NESTED NAME>: <NESTED VALUE OR OPTION>
//  DESCRIPTION CONTINUED ...>
//  - <NESTED VALUE OR OPTION>
//  - <NESTED VALUE OR OPTION>
//
// Examples
//
//   <CONFIGURATION EXAMPLE>
//   <CONFIGURATION EXAMPLE>

Example¶

// Console consumer
//
// This consumer reads from stdin or a named pipe. A message is generated after
// each newline character.
//
// Metadata
//
// - pipe: name of the pipe the message was received on
//
// Parameters
//
// - Pipe: Defines the pipe to read from. This can be "stdin" or the path
// of a named pipe. A named pipe is creared if not existing.
//
// - Permissions: Accepts an octal number string containing the unix file
// permissions used when creating a named pipe.
//
// - ExitOnEOF: Can be set to true to trigger an exit signal if the pipe is closed
// i.e. when EOF is detected.
//
// Examples
//
// This configuration reads data from standard-in.
//
//  ConsoleIn:
//    Type: consumer.Console
//    Streams: console
//    Pipe: stdin
type Console struct {
    core.SimpleConsumer `gollumdoc:"embed_type"`
        autoExit            bool   `config:"ExitOnEOF" default:"true"`
        pipeName            string `config:"Pipe" default:"stdin"`
        pipePerm            uint32 `config:"Permissions" default:"0644"`
        pipe                *os.File
}