Skip to content

Commit

Permalink
Add [float] to section headers
Browse files Browse the repository at this point in the history
This fixes some crazy asciidoc => docbook XML => html conversion
stuff that our current doc process uses.

Fixes elastic#2478
  • Loading branch information
untergeek authored and jordansissel committed Jan 29, 2015
1 parent 026b8c8 commit 5a5ebd7
Showing 1 changed file with 35 additions and 1 deletion.
36 changes: 35 additions & 1 deletion docs/asciidoc/static/include/pluginbody.asciidoc
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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:

Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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`:
Expand All @@ -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"]
Expand Down Expand Up @@ -424,6 +436,7 @@ output {
----------------------------------
endif::encode_method[]

[float]
=== Configuration Parameters
[source,ruby]
----------------------------------
Expand All @@ -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}
Expand All @@ -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"]
Expand Down Expand Up @@ -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"]
Expand Down Expand Up @@ -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"]
Expand All @@ -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"]
Expand All @@ -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]
Expand Down Expand Up @@ -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"]
Expand Down Expand Up @@ -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"]
Expand All @@ -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
Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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.

Expand Down Expand Up @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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")].
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 5a5ebd7

Please sign in to comment.