Add guidelines for writing plugin doc

Fix link formatting

Fixes #9861

docs/index.asciidoc

@@ -235,6 +235,11 @@ include::static/codec.asciidoc[]
 include::static/filter.asciidoc[]
 include::static/output.asciidoc[]
 
+// Plugin doc guidelines
+
+:edit_url: https://github.com/elastic/logstash/edit/{branch}/docs/static/doc-for-plugin.asciidoc
+include::static/doc-for-plugin.asciidoc[]
+
 // Contributing a Patch to a Logstash Plugin
 
 :edit_url: https://github.com/elastic/logstash/edit/{branch}/docs/static/contributing-patch.asciidoc

docs/static/contributing-to-logstash.asciidoc

@@ -1,24 +1,21 @@
 [[contributing-to-logstash]]
 == Contributing to Logstash
 
-Before version 1.5, Logstash included all plugins in each release.  This made it
-easy to make use of any plugin, but it complicated plugin development--a new
-release of Logstash became necessary if a plugin needed patching.  Since version
-1.5, all plugins are independent of the Logstash core. Now you can add your own
-input, codec, filter, or output plugins to Logstash much more easily!
+You can add your own input, codec, filter, or output plugins to Logstash. 
 
 [float]
 === Adding plugins
 
-Since plugins can now be developed and deployed independently of the Logstash
-core, there are documents which guide you through the process of coding and
-deploying your own plugins:
+Plugins can be developed and deployed independently of the Logstash
+core. Here are some documents to guide you through the process of coding and
+deploying your own plugin:
 
 * <<plugin-generator,Generating a New Plugin>>
-* http://www.elasticsearch.org/guide/en/logstash/current/_how_to_write_a_logstash_input_plugin.html[How to write a Logstash input plugin]
-* http://www.elasticsearch.org/guide/en/logstash/current/_how_to_write_a_logstash_codec_plugin.html[How to write a Logstash codec plugin]
-* http://www.elasticsearch.org/guide/en/logstash/current/_how_to_write_a_logstash_filter_plugin.html[How to write a Logstash filter plugin]
-* http://www.elasticsearch.org/guide/en/logstash/current/_how_to_write_a_logstash_output_plugin.html[How to write a Logstash output plugin]
+* <<input-new-plugin,How to write a Logstash input plugin>>
+* <<input-new-plugin,How to write a Logstash codec plugin>>
+* <<input-new-plugin,How to write a Logstash filter plugin>>
+* <<input-new-plugin,How to write a Logstash output plugin>>
+* <<plugin-doc,Documenting your plugin>>
 * <<contributing-patch-plugin,Contributing a Patch to a Logstash Plugin>>
 * <<community-maintainer,Community Maintainer's Guide>>
 * <<submitting-plugin,Submitting a Plugin>>
@@ -26,8 +23,7 @@ deploying your own plugins:
 [float]
 ==== Plugin Shutdown APIs
 
-Starting in Logstash 2.0, we changed how input plugins shut down to increase shutdown reliability. There are three methods
-for plugin shutdown: `stop`, `stop?`, and `close`.
+You have three options for shutting down a plugin: `stop`, `stop?`, and `close`.
 
 * Call the `stop` method from outside the plugin thread. This method signals the plugin to stop.
 * The `stop?` method returns `true` when the `stop` method has already been called for that plugin.

docs/static/doc-for-plugin.asciidoc

@@ -0,0 +1,76 @@
+[[plugin-doc]]
+=== Documenting your plugin
+
+Quality documentation with good examples contributes to the adoption of your plugin.
+
+The documentation for your plugin will be generated and published in the
+{logstash-ref}/index.html[Logstash Reference] and the
+{lsplugindocs}[Versioned plugin docs].
+
+[[plugin-doc-file]]
+==== Documentation file
+
+Documentation should be included in your plugin structure as a single file called 'docs/index.asciidoc'.
+
+[[heading-ids]]
+==== Heading IDs
+
+Heading IDs must be in a format that supports generated IDs. This approach
+creates unique IDs when the
+{lsplugindocs}[Versioned plugin docs] are generated.
+
+*Example*
+
+Don't hardcode a heading ID like this: `[[config_models]]`
+
+Instead, define it like this:
+
+[source,txt]
+----------------------------------
+[id="plugins-{type}s-{plugin}-config_models"]
+==== Configuration models
+----------------------------------
+
+If you hardcode an ID, the versioned plugin docs will build correctly the
+first time. The second time the doc build runs, the ID will be flagged as
+a duplicate, and the build will fail.
+
+[[format-code]]
+==== Code samples
+
+We all love code samples. Asciidoc supports code blocks and config examples.
+To include Ruby code, use the asciidoc `[source,ruby]` directive.
+
+Note that the hash marks (#) are present to make the example render correctly.
+Don't include the hash marks in your asciidoc file.
+
+[source,txt]
+[subs="attributes"]
+----------------------------------
+# [source,ruby]
+# ----------------------------------
+# match => {
+#  "field1" => "value1"
+#  "field2" => "value2"
+#  ...
+# }
+# ----------------------------------
+----------------------------------
+
+This sample renders in the documentation like this:
+[source,ruby]
+----------------------------------
+match => {
+  "field1" => "value1"
+  "field2" => "value2"
+  ...
+}
+----------------------------------
+
+
+==== Resources
+
+For more asciidoc formatting tips, see the excellent reference at
+https://github.com/elastic/docs#asciidoc-guide
+
+

docs/static/include/pluginbody.asciidoc

@@ -1,4 +1,4 @@
-
+[id="{plugintype}-new-plugin"]
 
 === How to write a Logstash {plugintype} plugin
 
@@ -344,49 +344,14 @@ them here along with these Logstash dependencies.
 
 Let's go through the various elements of the plugin itself.
 
-==== Inline Documentation
-Logstash provides infrastructure to automatically generate documentation for
-plugins. We use the asciidoc format to write documentation so _any_ comments in
-the source code will be first converted into asciidoc and then into html.
+==== Documentation for your plugin
+Documentation is an important part of your plugin. All plugin documentation is
+rendered and placed in the 
+http://www.elasticsearch.org/guide/en/logstash/current/index.html[Logstash
+Reference] and the {lsplugindocs}[Versioned plugin docs].
 
-All plugin documentation is then rendered and placed in
-http://www.elasticsearch.org/guide/en/logstash/current/index.html[the Logstash section of the Elasticsearch Guide].
+See <<plugin-doc>> for tips and guidelines.
 
-The inline documentation can include code blocks and config examples! To include
-Ruby code, use the asciidoc `[source,ruby]` directive:
-
-[source,txt]
-[subs="attributes"]
-----------------------------------
-# Using hashes:
-# [source,ruby]
-# ----------------------------------
-# match => {
-#  "field1" => "value1"
-#  "field2" => "value2"
-#  ...
-# }
-# ----------------------------------
-----------------------------------
-
-In the rendered HTML document, this block would look like:
-
-[]
-=========================
-Using hashes:
-[source,ruby]
-----------------------------------
-match => {
-  "field1" => "value1"
-  "field2" => "value2"
-  ...
- }
-----------------------------------
-=========================
-
-
-TIP: For more asciidoc formatting tips, see the excellent reference at
-https://github.com/elastic/docs#asciidoc-guide
 
 ==== `class` Declaration
 The {plugintype} plugin class should be a subclass of
@@ -1275,11 +1240,11 @@ we always welcome new plugins!
 Some of the many benefits of having your plugin in the logstash-plugins
 repository are:
 
-* **Discovery** Your plugin will appear in the http://www.elasticsearch.org/guide/en/logstash/current/index.html[Logstash Reference],
+* **Discovery.** Your plugin will appear in the http://www.elasticsearch.org/guide/en/logstash/current/index.html[Logstash Reference],
 where Logstash users look first for plugins and documentation.
-* **Documentation** Your plugin documentation will automatically be added to the
+* **Documentation.** Your plugin documentation will automatically be added to the
  http://www.elasticsearch.org/guide/en/logstash/current/index.html[Logstash Reference].
-* **Testing** With our testing infrastructure, your plugin will be continuously
+* **Testing.** With our testing infrastructure, your plugin will be continuously
 tested against current and future releases of Logstash.  As a result, users will
 have the assurance that if incompatibilities arise, they will be quickly
 discovered and corrected.