Quality issues in the plugin docs (incorrect asciidoc formatting, missing content)

[dedemorton]

Ran across the following quality issues when I was scanning the input plugin docs for docgen issues.

Global:

• Style of the description varies from plugin to plugin. Would be nice to make the descriptions for consistent in style (at least for the plugins that we maintain).

Input plugins:

• In plugin-inputs-beats, text overruns navigation.
• In plugins-inputs-cloudwatch:
  • Only 1 of the 3 examples is properly formatted as JSON.
  • "Configuration Example" heading is formatted incorrectly
  • "Configuration Example" should be sentence case and plural
  • List under filter option needs returns to render correct. Correct typos.
• In plugins-inputs-couchdb_changes, the intro has a couple of section titles that are incorrectly formatted.
• Edit plugins-inputs-file
• In plugins-inputs-gelf, the example is not correctly formatted as xml.
• In plugins-inputs-gemfire:
• Note is not formatted (needs to say NOTE: instead of Note: to get the correct formatting).
• Example under cache_xml_file is not correctly formatted as XML.
• ⭐️ In plugins-inputs-http_poller:
• Description of validate_after_inactivity option contains weird formatting and # sign.
• This topic needs an edit. Contains typos, missing periods, etc.
• See Document "headers" as part of the config options logstash-plugins/logstash-input-http_poller#99
• In plugins-inputs-imap, lots of options are missing descriptions.
• In multiple plugins, the example shown under the id option is incorrectly formatted. This must be boiler plate text that's reused from somewhere.
• In plugins-inputs-jmx, ## The configuration: should be formatted as a subheading. (Fix configuration heading LOGSTASH-176 - add type and tag filtering to graphite output #46)
• In plugins-inputs-kafka:
• The contents of the decorate_events description should be formatted as a list.
• https://www.elastic.co/guide/en/logstash/current/plugins-inputs-kafka.html#plugins-inputs-kafka-partition_assignment_strategy maps to kafka's partition.assignment.strategy property. (Rob/Chad-6-4-18)
• In plugins-inputs-lumberjack, URL is formatted in markup style, not asciidoc.
• In plugins-inputs-pipe, description of the command option includes text that begins TODO(sissel):.
• REMOVED plugins-inputs-rackspace contains no intro description.
• REMOVED plugins-inputs-zenoss contains no intro description.

Output Plugins:

• plugins-outputs-boundary:
• needs an edit. What do people have against periods anyhow? Some of the descriptions are hard to follow.
• In multiple plugins, the description of workers says, "TODO remove this in Logstash 6.0 when we no longer support the :legacy type This is hacky, but it can only be herne"
• plugins-outputs-csv needs an edit.
• plugins-outputs-datadog:
• Needs an edit.
• Fixed: The intro is in the wrong place, so it's not being pulled into the topic.
• Descriptions of the available options aren't very useful.
• In plugins-outputs-elasticsearch, we point to an old blog from 2013. Not sure we should be doing that. Someone should at least confirm that the blog is still accurate.
• In plugins-outputs-elasticsearch, add a note about migration from doc to _doc
• In plugins-outputs-google_bigquery:
• Intro needs asciidoc tagging (sections plus examples properly tagged).
• plugins-outputs-google_cloud_storage has the same issues as above.
• plugins-outputs-graphtastic needs an edit. The writing seems almost confessional.
• In plugins-outputs-http, the intro description is missing because it's in the wrong place in the source file.
• In plugins-outputs-kafka
  • Fixed: text in table overruns navigation.
  • Formatting of options described under acks could be better.
• In plugins-outputs-librato, the intro description is missing because it's in the wrong place in the source file.
• plugins-outputs-lumberjack contains no intro description.
• plugins-outputs-mongodb contains no intro description.
• In plugins-outputs-nagios_nsca, the example is not correctly formatted (gets broken into 2 examples).
• REMOVED plugins-outputs-rackspace contains no intro description.
• plugins-outputs-redmine needs an edit. Cringe-worthy typos.
• In plugins-outputs-riemann, looks like the example coding might be off.
• plugins-outputs-s3 contains multiple formatting issues (incorrectly formatted bullet lists, headings, etc).
• plugins-outputs-stomp contains no intro description.

Filter plugins:

• In filters-elapsed, correct default coding for periodic_flush. See discussion in #36
• In plugins-filters-cipher, formatting for default value and value type is messed up (not sure if this is an asciidoc issue or the doc gen).
• Bug in plugins-filters-dns--edit link takes you to dissect.rb source.
• Bug in plugins-filters-dissect--edit link takes you to dns.rb source.
• In plugins-filters-dns.html, the description of the reverse option includes to-do items: TODO(sissel): The timeout limitation does seem to be fixed in here: http://redmine.ruby-lang.org/issues/5100 # but isn’t currently in JRuby. TODO(sissel): make action required? This was always the intent, but it due to a typo it was never enforced. Thus the default behavior in past versions was append by accident. Reverse resolve one or more fields.
• In plugins-filters-dissect, some of the examples don't use the correct asciidoc example formatting type for the data that's shown. The docs are also very hard to follow. This is an important plugin.
• In plugins-filters-drop, some of the examples don't use the correct asciidoc example formatting type for the data that's shown.
• In plugins-filters-mutate, add an example to illustrate nesting
• In plugins-filters-elapsed, some of the examples don't use the correct asciidoc example formatting type for the data that's shown.
• In plugins-filters-environment, some of the examples don't use the correct asciidoc example formatting type for the data that's shown.
• REMOVED plugins-filters-metaevent contains no intro description.
• In plugins-filters-metricize, the examples in the intro don't use the correct example formatting.
• REMOVEd In plugins-filters-oui, for example under the source option needs to be formatted.
• **In plugins-filters-throttle. Has been removed from CI.
  • some of the example formatting is messed up with the example being broken into a mixture of example and text.**
• REMOVED In plugins-filters-zeromq, the bullet list in the intro isn't formatted correctly.

Codec plugins:

• In plugins-codecs-cef, the example under the delimiter option needs to be formatted correctly
• REMOVED plugins-codecs-cloudtrail doesn't really contain any doc content.
• REMOVED plugins-codecs-compress_spooler does not contain an intro description. In fact, there's very little doc here. There is a description for min_flush_time in the Ruby source, but it doesn't appear in the docs (maybe it's newish??)
• plugins-codecs-dots doesn't really contain any doc content. Needs an example at least.
• plugins-codecs-edn doesn't really contain any doc content. Added description, but still needs an example.
• plugins-codecs-edn_lines doesn't really contain any doc content. Added description, but still needs an example
• plugins-codecs-msgpack doesn't really contain any doc content. Added description, but still needs an example.
• In plugins-codecs-nmap, the list of event types should be formatted as a list.
• In plugins-codecs-protobuf, link is formatted incorrectly and bullet list under the include_path option needs formatting.

Meta:

• In filters-elapsed, correct default coding for periodic_flush. See discussion in #36. NOTE: From CS: "I just looked at Quality issues in the plugin docs (incorrect asciidoc formatting, missing content) #6693 and note that this also impacts the metrics, aggregate, multilines and throttle filters (per my quick search ^^)"

[dedemorton]

@karenzone This issue has been open for quite awhile because I use it to track and fix little nits that I notice in the plugin docs. Whenever you need to update the docs for a plugin, make sure you check this issue to see if there are any other fixes required.

[karenzone]

Most of the issues have been addressed. Moving unchecked issues to #10838 for research and remediation.

Thanks for creating this meta issue and model for tracking quality issues in the plugin docs, DeDe. The good work you started lives on in #10838.