From 5a5ebd7e5893ff6e1c64bb63be3e96004d5d6133 Mon Sep 17 00:00:00 2001 From: Aaron Mildenstein Date: Thu, 29 Jan 2015 15:10:42 -0700 Subject: [PATCH] Add [float] to section headers This fixes some crazy asciidoc => docbook XML => html conversion stuff that our current doc process uses. Fixes #2478 --- .../static/include/pluginbody.asciidoc | 36 ++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/docs/asciidoc/static/include/pluginbody.asciidoc b/docs/asciidoc/static/include/pluginbody.asciidoc index bbb7b27f18c..9b358fdf1f1 100644 --- a/docs/asciidoc/static/include/pluginbody.asciidoc +++ b/docs/asciidoc/static/include/pluginbody.asciidoc @@ -1,7 +1,7 @@ :branch: 1.5 :ls_version: 1.5.0.beta1 -= How to write a Logstash {plugintype} plugin +== How to write a Logstash {plugintype} plugin To develop a new {plugintype} for Logstash, you build a self-contained Ruby gem whose source code lives in its own GitHub repository. The Ruby gem can then be @@ -14,10 +14,12 @@ NOTE: As of Logstash 1.5, all plugins are self-contained Ruby gems. This change makes it possible to develop and release plugins separately. In previous versions, plugins were part of the core Logstash distribution. +[float] == Get started {getstarted} +[float] === Create a GitHub repo for your new plugin Each Logstash plugin lives in its own GitHub repository. To create a new repository for your plugin: @@ -30,8 +32,10 @@ Each Logstash plugin lives in its own GitHub repository. To create a new reposit ** **Initialize this repository with a README** -- enables you to immediately clone the repository to your computer. . Click **Create Repository**. +[float] === Copy the {plugintype} code +[float] ==== Build your local repository . **Clone your plugin.** Replace `GITUSERNAME` with your github username, and `MYPLUGINNAME` with your plugin name. @@ -88,6 +92,7 @@ For more information about the Ruby gem file structure and an excellent walkthrough of the Ruby gem creation process, see http://timelessrepo.com/making-ruby-gems +[float] === See what your plugin looks like Before we dive into the details, open up the plugin file in your favorite text editor and take a look. @@ -280,10 +285,12 @@ end # class LogStash::{pluginclass}::{pluginnamecap} ---------------------------------- endif::receive_method[] +[float] == Coding {plugintype} plugins Now let's take a line-by-line look at the example plugin. +[float] === `encoding` It seems like a small thing, but remember to specify the encoding at the @@ -297,6 +304,7 @@ beginning of your plugin code: Logstash depends on things being in UTF-8, so we put this here to tell the Ruby interpreter that we’re going to be using the UTF-8 encoding. +[float] === `require` Statements Logstash {plugintype} plugins require parent classes defined in @@ -312,10 +320,12 @@ require "logstash/namespace" Of course, the plugin you build may depend on other code, or even gems. Just put them here along with these Logstash dependencies. +[float] === Plugin Body Let's go through the various elements of the plugin itself. +[float] ==== Inline Documentation Logstash provides infrastructure to automatically generate documentation for plugins. We use the asciidoc format to write documentation so _any_ comments in @@ -360,6 +370,7 @@ match => { TIP: For more asciidoc formatting tips, see the excellent reference at https://github.com/elasticsearch/docs#asciidoc-guide +[float] === `class` Declaration A {plugintype} plugin class should be a subclass of `LogStash::pass:attributes[{pluginclass}]::Base`: @@ -376,6 +387,7 @@ The class name should closely mirror the plugin name, for example: LogStash::{pluginclass}::{pluginnamecap} ---- +[float] === `config_name` [source,ruby] [subs="attributes"] @@ -424,6 +436,7 @@ output { ---------------------------------- endif::encode_method[] +[float] === Configuration Parameters [source,ruby] ---------------------------------- @@ -446,6 +459,7 @@ will become a valid boolean in the config. This coercion works for the `false`) * `:deprecated` - informational (also a Boolean `true` or `false`) +[float] === Plugin Methods {methodheader} @@ -454,6 +468,7 @@ will become a valid boolean in the config. This coercion works for the // If register_method is defined (should be all types) // ///////////////////////////////////////////////////////////////////////////// ifdef::register_method[] +[float] ==== `register` Method [source,ruby] [subs="attributes"] @@ -481,6 +496,7 @@ endif::register_method[] // If filter_method is defined (should only be for filter plugin page) // ///////////////////////////////////////////////////////////////////////////// ifdef::filter_method[] +[float] ==== `filter` Method [source,ruby] [subs="attributes"] @@ -520,6 +536,7 @@ endif::filter_method[] // If decode_method is defined (should only be for codec plugin page) // ///////////////////////////////////////////////////////////////////////////// ifdef::decode_method[] +[float] ==== `decode` Method [source,ruby] [subs="attributes"] @@ -546,6 +563,7 @@ endif::decode_method[] // If encode_method is defined (should only be for codec plugin page) // ///////////////////////////////////////////////////////////////////////////// ifdef::encode_method[] +[float] ==== `encode` Method [source,ruby] [subs="attributes"] @@ -569,6 +587,7 @@ endif::encode_method[] // If run_method is defined (should only be for input plugin page) // ///////////////////////////////////////////////////////////////////////////// ifdef::run_method[] +[float] ==== `run` Method The `pass:attributes[{pluginname}]` input plugin has the following `run` Method: [source,ruby] @@ -653,6 +672,7 @@ endif::run_method[] // If receive_method is defined (should only be for output plugin page) // ///////////////////////////////////////////////////////////////////////////// ifdef::receive_method[] +[float] ==== `receive` Method [source,ruby] [subs="attributes"] @@ -695,6 +715,7 @@ endif::receive_method[] // If teardown_method is defined (should only be for input or output plugin page) // ///////////////////////////////////////////////////////////////////////////// ifdef::teardown_method[] +[float] ==== `teardown` Method [source,ruby] [subs="attributes"] @@ -710,10 +731,12 @@ threads are all closed down properly. If your plugin uses these connections, you should include a teardown method. endif::teardown_method[] +[float] == Building the Plugin At this point in the process you have coded your plugin and are ready to build a Ruby Gem from it. The following steps will help you complete the process. +[float] === Add a Gemfile Gemfiles allow Ruby's Bundler to maintain the dependencies for your plugin. Currently, all we'll need is the Logstash gem, for testing, but if you require @@ -729,6 +752,7 @@ gemspec gem "logstash", :github => "elasticsearch/logstash", :branch => "{branch}" ---------------------------------- +[float] === Add a `gemspec` file Gemspecs define the Ruby gem which will be built and contain your plugin. @@ -800,6 +824,7 @@ This plugin should work but would benefit from use by folks like you. Please let You will no longer see a message indicating potential code immaturity when a plugin reaches version 1.0.0 +[float] ==== Runtime & Development Dependencies At the bottom of the `gemspec` file is a section with a comment: `Gem dependencies`. This is where any other needed gems must be mentioned. If @@ -827,6 +852,7 @@ and less than version 2.0 `'< 2.0.0'`. IMPORTANT: All plugins have a runtime dependency on the `logstash` core gem, and a development dependency on `logstash-devutils`. +[float] === Add Tests Logstash loves tests. Lots of tests. If you're using your new {plugintype} plugin in a production environment, you'll want to have some tests to ensure you @@ -839,6 +865,7 @@ For help learning about tests and testing, look in the `spec/pass:attributes[{plugintype}]s/` directory of several other similar plugins. +[float] === Clone and test! Now let's start with a fresh clone of the plugin, build it and run the tests. @@ -870,9 +897,11 @@ Finished in 0.034 seconds Hooray! You're almost there! (Unless you saw failures... you should fix those first). +[float] === Building and Testing Now you're ready to build your (well-tested) plugin into a Ruby gem. +[float] ==== Build You already have all the necessary ingredients, so let's go ahead and run the build command: @@ -892,6 +921,7 @@ logstash-{plugintype}-mypluginname-0.1.0.gem The `s.version` number from your gemspec file will provide the gem version, in this case, `0.1.0`. +[float] ==== Test installation You should test install your plugin into a clean installation of Logstash. Download the latest version from the @@ -1067,12 +1097,14 @@ endif::receive_method[] Congratulations! You've built, deployed and successfully run a Logstash {plugintype}. +[float] == Submitting your plugin to http://rubygems.org[RubyGems.org] and https://github.com/logstash-plugins[logstash-plugins] Logstash uses http://rubygems.org[RubyGems.org] as its repository for all plugin artifacts. Once you have developed your new plugin, you can make it available to Logstash users by simply publishing it to RubyGems.org. +[float] === Licensing Logstash and all its plugins are licensed under https://github.com/elasticsearch/logstash/blob/master/LICENSE[Apache License, version 2 ("ALv2")]. @@ -1081,6 +1113,7 @@ please make sure to have this line in your gemspec: * `s.licenses = ['Apache License (2.0)']` +[float] === Publishing to http://rubygems.org[RubyGems.org] To begin, you’ll need an account on RubyGems.org @@ -1136,6 +1169,7 @@ by running: bin/plugin install logstash-{plugintype}-mypluginname ---------------------------------- +[float] === Contributing your source code to https://github.com/logstash-plugins[logstash-plugins] It is not required to contribute your source code to https://github.com/logstash-plugins[logstash-plugins] github organization, but