[Meta] Enhancements and fixes to Logstash doc tooling

[karenzone]

Here's a list of fixes and enhancement requests that could save time, reduce risk of human error, and improve the quality of our documentation.

Strategic enhancements:

• Validate doc changes (asciidoc formatting, cross-document links) for plugin doc source #42 and related:
  • https://github.com/elastic/ingest-dev/issues/4776
  • Create infrastructure for testing plugin docs for a single plugin #19
  • Add enhanced CI to capture common doc problems #84
• VPR: Adjust tooling to improve workflow for adding new integration plugin docs #90
  • Possible workaround: VPR: Revisit allowing a non-standard landing page (use case: new integrations) #89
• Add enhanced CI to capture common doc problems #84
• Release notes script: change output from asciidoc to json logstash#13492
  The new docs system is coming. We're breaking down product silos, and release notes/feature highlights/what's new will have a Elastic (not product) focus. The content will be easily searchable and filterable. The move to json output for release notes is an important milestone toward this effort.
• Versioned Plugin Reference docgen periodically pruned #109

Priority fixes/enhancements:

• Versioned Plugins Reference failures are bringing down docs build for elastic.co #51
• Unexpected value for default_plugin setting #56 (was https://github.com/elastic/logstash/issues/12939 before transfer)
• Docs for output-elastic_app_search not getting updated properly #57
• Update plugin doc generation tooling beyond Java 8 #64
• VPR jenkins job generates content but doesn't create a PR #66
• [@mashhurs] Plugin doc generation: preserve content in logstash-docs if no version bump #45
  • Why? Plugins are not versioned, and all changes come from main. When we have mismatches with content in older versions, I have to remove regressions manually. The original design intent is that no new content gets picked up unless accompanied by a version bump. Re-implementing that behavior would solve this issue. Sample of manual workflow: Updated docs for 6.8 with regressions removed logstash-docs#1264
  • PR: Skip doc generation if no plugin version up. #72
• [@mashhurs] Evaluate automating docs generation for aliased plugins #52
  • Why? Doc tooling does not support aliasing. Keeping docs insync between input-beats and input-elastic_agent is a manual process for all branches. Samples of manual workflow: Manual process: Update input-elastic_agent to v6.2.2 logstash-docs#1212 and ManualProcess: Update input-elastic_agent to v6.2.4 for main logstash-docs#1255.
  • PR: A doc generator implementation for aliased plugin. #68
• [@mashhurs] Solve versioning between VPR and stack docs #46
  • PR: Support stack versions in versioned plugin docs. #70
  • Implement versioning between VPR and stack docs #76
• [@mashhurs] Validate doc changes (asciidoc formatting, cross-document links) for plugin doc source #42
• Docs for some integration plugin components aren't getting updated #80
• Plugin doc generation: preserve content in logstash-docs if no version bump (integrations) #79
• Reference Doc Github action: Make it easier to see which branch corresponds to each job #67
• Commits by Reference Documentation github action leave out branch #71
• [@mashhurs] Add alias params declarations in logstash AliasRegistry.yml and manipulate in doc-tools #69
  • PR: A structural change for aliased plugin declarations to support alias doc headers. logstash#13971
• [@mashhurs] Link current stack version instead feature releases. #74
  • PR: Link current stack version instead feature releases. #75

Important fixes:

• VPR: Allow adding a non-standard landing page (manually or programmatically)  #53 The immediate need (aliased plugins) has been addressed with a specialized solution. Still, chances are good we might need this capability in the future.
• VPR: Add link to "how to fix" document when VPR docgen fails #62
• Revisit and evaluate skiplists #50
  • Add input-log4j to skiplist #49
• Plugin docgen with no changes shouldn't be considered a FAILURE #43
• #831: [ingest-dev]InternalDocs: Validate steps and update doc for manually generating plugin docs #831. Update: The problem was environmental. Need to document env requirements. Requirements and processes may change with new docs system, so on HOLD for now.

Reevaluate and triage:

• Integration Plugin Support: Refactor for clarity #34
• Logstash versioned plugins build failures vs auto-PR and required manual cleanup #21
• split versioned plugin doc generation ci job into two #18
• programatically generate plugin-type asciidocs  #7
• Generate list of commercially supported (via support contracts) #1

[karenzone]

@roaksoax I opened the docs tooling meta issue as you requested. I'll flesh it out with more details and description soon. At least now it won't be as easy to lose or forget. :-)