Doc: Migration from standalone to integration plugin

[karenzone]

Starts with @edmocosta's great work in #14 and expands it.

Design intent

• The migration steps are necessary because of the new integration plugin that pulls in input-snmp and input-snmptrap. The migration content is big news for now and needs to be super-obvious. For that reason, I recommend that we include the migration info in the integration topic and link to it from banners in the the component plugins. With this approach, we don't have to decide between adding heavy, "moment in time" content to the beginning of a topic where it will push down other content, OR add it to the end where it might be missed.

• Note that distinguishing between old and new versions of the snmp inputs is tricky. I tried to be as precise as possible, and starting introducing language such as "preview version," "stand-alone," "next generation," and so forth. I'm bound to find more instances where we need to be more clear, but this is start. Comments on the terminology I'm using are always welcome.

• You'll notice snmp and snmptrap repeated in headings and sub-headings. This is intentional. Users often scan content or can land in a section from a search. The repetition is designed to clearly indicate which plugin flavor the section applies to without leaving that responsibility to the user.

• Disclaimer: In order to validate structure and formatting, I had to mock up files because the integration plugin isn't generating doc files yet. This hack makes it easy to obscure problems with formats and links, so hang on!

@edmocosta, thanks for your great work on this. Let's discuss this approach and decide on next steps.

Fixes: #11

[karenzone]

@edmocosta this work adds quite a few links and dependencies. I'm wondering if it makes sense to generate docs, and then to follow on immediately with the migration guides. Let's discuss! :-)

[karenzone]

You can see a mocked up version of the snmp docs here:

• https://logstash-docs_bk_1631.docs-preview.app.elstc.co/guide/en/logstash/master/plugins-integrations-snmp.html
• https://logstash-docs_bk_1631.docs-preview.app.elstc.co/guide/en/logstash/master/plugins-inputs-snmp.html
• https://logstash-docs_bk_1631.docs-preview.app.elstc.co/guide/en/logstash/master/plugins-inputs-snmptrap.html

[karenzone]

@edmocosta, thank you for your comments. I added your suggestion and committed another fix that got my mocked up files building. 🎉

As mentioned earlier, my test files are mocked up "because the integration plugin isn't generating doc files yet. This hack makes it easy to obscure problems with formats and links, so hang on!" We should be able to quickly resolve any glitches that come up when we merge and publish.

All that said... This content is ready to go. I believe you'd mentioned absorbing the contents of this PR into your branch? Or I can merge this one. However you want to proceed works for me. Please continue to keep me in the loop.

[edmocosta]

@edmocosta, thank you for your comments. I added your suggestion and committed another fix that got my mocked up files building. 🎉

As mentioned earlier, my test files are mocked up "because the integration plugin isn't generating doc files yet. This hack makes it easy to obscure problems with formats and links, so hang on!" We should be able to quickly resolve any glitches that come up when we merge and publish.

All that said... This content is ready to go. I believe you'd mentioned absorbing the contents of this PR into your branch? Or I can merge this one. However you want to proceed works for me. Please continue to keep me in the loop.

Thank you again @karenzone! could you please merge it? I'll update my branch later, no worries! :)