logstash/tools/logstash-docgen

Features

Generating the documentation for a Logstash instance

You can now generate the documentation for a Logstash distribution.

prerequisite:

• You need to have installed the plugins inside Logstash, this is necessary to pickup the right file when generating the documentation.
• You need to have the development gems installed. bin/logstash-plugin --no-verify --development

If you have all of the above you can run this command:

rake doc:generate-plugins
rake doc:generate-plugins[/tmp/the-new-doc] # Depending on the shell you are using you might need to quote the task name, like this rake "doc:generate-plugins[/tmp/new-doc]"

This will give you a output similar to this

logstash-input-file > SUCCESS
logstash-input-s3 > SUCCESS
logstash-input-kafka > FAIL
[...]
Exceptions: XXXX

The generator will try to generate the doc for all the plugins defined in the Gemfile and installed in Logstash, if anything goes wrong it won't stop the generation of the other plugin. The Task will also report any errors with stacktraces at the end, if one plugin fail the build, you can interrupt the process and it will output the current errors before exiting.

Generating the documentation for all the plugins from the organization

You can now generate the documentation from main for all the plugin in the logstash-plugins organization.

prerequisite

• You need to go in the tools/logstash-docgen directory
• You need to have the dependency installed.

To get started you can run the following commands:

cd tools/logstash-docgen
bundle install

You can use the bin/logstash-docgen command to generate any plugin that you want, this executable can generate all the plugins or specific one from their main branch.

Usages:

bin/logstash-docgen --all # will generate the doc for all the plugins
bin/logstash-docgen logstash-input-file logstash-input-s3 # generate doc for 2 plugins

See: bin/logstash-docgen --help for complete usage.

Notes:

• The nature of theses tasks require a lot of external execution to make sure all the doc are done in isolation, this process can take a long time.
• Some plugins will be skipped, see logstash-docgen.yml for details.
• The script will inject itself as a dependency on the plugin.

Testing the documentation as the plugin author

prerequisite

• Declare the logstash-docgen as development dependency
• Add require "logstash/docgen/plugin_doc" to the Rakefile
• Run bundle install

After you can have access to a few rake tasks, you can list them with bundle exec rake -T

bundle exec rake doc:asciidoc # return the raw asciidoc
bundle exec rake doc:html # Give you the raw html

CI test

The CI can use the ci/docs.sh script to correctly bootstrap and execute the docgeneration