Coordinate a plan for adding new integration docs

[karenzone]

Goal: Create an orderly plan for setting up and enabling a new plugin integration.
Even better: Use the new integration to improve our internal "how to" docs.
Best option: Let's fix the docs tooling so this isn't such an iterative, time-consuming pain and we don't need to document the workaround: elastic/docs-tools#90 with a possible solution outlined in elastic/docs-tools#89.

TL;DR: Setting up integration plugin docs is tricky because:

• An integration plugin is ambiguous from a tooling POV in that it is both a parent and a peer to standard input, output, filter, codec plugins.
• We can't generate content and link to the generated content in the same PR.

What makes setting up integration docs different from setting up docs for other plugin types?

Logstash plugin integrations bundle two or more traditional plugin types (inputs, output, filters, codecs) into a consolidated "parent" plugin.

An integration plugin is tricky from a docs point-of-view because it is considered a traditional plugin type on par with inputs, outputs, codecs, and filters, and yet is a container for other plugins. Integration plugins require a special header, and the docs setup requires precise order of operation.

Update

Better idea: Rather than jumping through hoops, let's fix the docs tooling: elastic/docs-tools#90

[karenzone]

Description of order of operations and current workflow: https://github.com/elastic/ingest-dev/issues/2262
Steps need to be validated with the next integration setup.

[karenzone]

@yaauie, here's the integrations issue we talked about. For integration plugins, we need to build in additional time to either:

• Manually hook up the integration docs, or
• Enhance VPR docs tooling to make it easier to add a new integration plugin

[karenzone]

@roaksoax, for the new integration, we'll need to build in time to either manually hook up the integration docs, or update the VPR docs tooling to make it easier to add a new integration plugin.

Can we decide on the best course of action and allocate time in a future sprint, please?

[karenzone]

@mashhurs: This is the issue describing the complexities of adding a new integration plugin to docs. As mentioned earlier in comments, we'll need to build in time to either https://github.com/elastic/ingest-dev/issues/2262, or elastic/docs-tools#90 (comment) to make it easier to add a new integration plugin.

[mashhurs]

@mashhurs: This is the issue describing the complexities of adding a new integration plugin to docs. As mentioned earlier in comments, we'll need to build in time to either elastic/ingest-dev#2262, or elastic/docs-tools#90 (comment) to make it easier to add a new integration plugin.

Thanks @karenzone for the details.
I went through them and I will coordinate with your once I sort out the baseline (bootstrap and SSL standardization) works.
And this PR is the start, which covers index, logstash-input and logstash-output pages only.

[mashhurs]

TODO list for logstash-integration-logstash plugin:

• Add logstash-integration-logstash to skip list
  • Skip logstash integration plugin for now because we are developing it. docs-tools#95
• Remove commented doc links in the logstash-integration-logstash
• Implement a workflow to add a placeholder for new plugin and create an index doc
• Remove logstash-integration-logstash from skip list
  • Remove logstash-integration-logstash plugin from the skip list after release to publish docs. docs-tools#96
• Release plugin
• Generate docs
  • make sure changes reflect into index docs

[karenzone]

Thanks for collaborating on this one, @mashhurs. The intent behind this one was to raise awareness for the issue and to get a plan in place. Now that we have a solid go-forward plan, I'm closing this one as complete.