plugin-docgen

plugin json doc generator

The plugin JSON documentation generation tool that generates a JSON document from a plugin that can be used to generate documentation in the Celerity Registry.

Installation

go install github.com/newstack-cloud/celerity/tools/plugin-docgen/cmd/celerity-plugin-docgen@latest

This will install the celerity-plugin-docgen tool in either the $GOBIN directory, which by default will be $GOPATH/bin. You'll need to be sure to add this directory to your PATH if it is not already included. You can specify a version by replacing latest with the desired version tag.

Usage

1. You will need to build your plugin and store the plugin in a location that follows the Celerity plugin directory structure. The plugin directory structure is as follows:

├── {plural(pluginType)}
│   ├── {host}? - (only required if the plugin is a part of a private or alternative registry)
│   │   ├── {namespace}
│   │   │   ├── {pluginName}
│   │   │   │    ├── {version}
│   │   │   │    │   ├── plugin

For example (a plugin for the official Celerity registry):

├── providers
│   ├── newstack-cloud
│   │   ├── aws
│   │   │    ├── 1.0.0
│   │   │    │   ├── plugin

Or a plugin for a private registry:

├── providers
│   ├── labs.company.io
│   │   ├── my-namespace
│   │   │    ├── my-plugin
│   │   │    │   ├── 1.0.0
│   │   │    │   ├── plugin

1. Get the absolute path of the parent directory of the top-level directory in the plugin directory structure. For example, if the plugin is located at /path/to/my/plugin/root/providers/newstack-cloud/aws/1.0.0/plugin, the absolute path would be /path/to/my/plugin/root.

2. Set environment variables and run the command:

# This is a place for the tool to store logs that collect that stdout and stderr output from the plugin.
export CELERITY_PLUGIN_DOCGEN_PLUGIN_LOG_FILE_ROOT_DIR="/path/for/plugin/logs"
# The absolute path to the directory from step 2.
export CELERITY_DEPLOY_ENGINE_PLUGIN_PATH="/path/to/my/plugin/root"
celerity-plugin-docgen -plugin={plugin}

Replace {plugin} with the unique ID of your plugin. (e.g. newstack-cloud/aws)

1. If the tool was successful, it will generate a docs.json file in the current working directory. This should then be published as a part of the release workflow so it can be used by a registry (e.g. the official Celerity Registry) to render HTML documentation.

Environment Configuration

Plugin Path

CELERITY_DEPLOY_ENGINE_PLUGIN_PATH

required

The absolute path to the root directory from which the tool can discover the plugin. See Usage for more details on preparing the directory structure.

Log File Root Directory

CELERITY_PLUGIN_DOCGEN_PLUGIN_LOG_FILE_ROOT_DIR

required

The absolute path to the directory where the tool will store logs that collect the stdout and stderr output from the plugin.

Plugin Launch Timeout

CELERITY_PLUGIN_DOCGEN_PLUGIN_LAUNCH_WAIT_TIMEOUT_MS

optional

The amount of time in milliseconds that the tool will wait for plugins to launch before timing out.

default value: 10000 (10 seconds)

Generate Docs Timeout

CELERITY_PLUGIN_DOCGEN_GENERATE_TIMEOUT_MS

optional

The amount of time in milliseconds that the tool will wait for the plugin to generate the documentation before timing out.

default value: 30000 (30 seconds)

Logging Level

CELERITY_PLUGIN_DOCGEN_LOG_LEVEL

optional

The logging level for the tool. This can be set to debug, info, warn, or error. This will control the verbosity of the logs that are generated by the tool as a host for the plugin.

default value: info

Additional documentation

• Contributing