Validate doc changes (asciidoc formatting, cross-document links) for plugin doc source - ON HOLD

[karenzone]

The logstash and logstash-docs repos now have the ability to do a complete doc build and throw errors if there are asciidoc formatting errors, bad cross-document links, etc. Our plugin docs are spread out in repos throughout the logstash-plugins org. Any doc errors don't manifest until we generate and transform the plugin docs, and they land in logstash-docs.

Could we validate doc changes sooner?

This enhancement has been needed for a long time. See Create infrastructure for testing plugin docs for a single plugin #19. It was closed due to inactivity, not because it was resolved.

UPDATED: ~This issue is especially painful because of a regression that passes a bad Logstash Versioned Plugin Reference to the elastic doc build and then crashes it: #51~ Thankfully, this issue has been resolved.

[karenzone]

@roaksoax Here's the issue you requested. Please feel free to add additional commentary. Thanks!

[karenzone]

@mashhurs Thank you for looking into this. This is an interesting one, and it will require some planning and design. As we have discussed, the source doc in the plugin repo has unset variables.

When we generate plugin docs (for either the LSR or the VPR), those variables are populated with relevant info... plugin version, release date, etc.

I need 1.) those values to be populated and 2.) the file to be pulled into the LSR framework before I can build and test. As a work-around, I make (or fake?) my own test harness. :-)

My current workflow to test plugin doc changes locally

IMPORTANT: I am not proposing replicating this workflow in the solution. This info is here as an explanation of the workaround to achieve the necessary results.

1. Open the most recently generated version of the plugin doc file in logstash-docs repo. That is, I open my local copy of the elasticsearch output in the logstash-docs repo if I want to test changes to the elasticsearch output source file.
2. Open the doc source file in the PR. Copy all the content from approximately Line 16 ([id="plugins-{type}s-{plugin}"]) to the end of the file. Paste it into the generated version of the plugin doc file.
3. Run a command to build the Logstash Reference locally.
4. Review the output (in logstash-docs).
5. Check:
   • Does the book build correctly? (Be sure that the changes don't cause the doc build to throw errors and fail to build.)
   • Do these changes render correctly? Is the formatting correct? (Example: Bulleted lists are notorious for building without error, but rendering as a single paragraph of text.)
   • Do these changes contain any cross-doc links that might not resolve correctly, and would break the elastic.co docs build? (I can do a full elastic.co docs build locally, but don't spend the time if there are no new cross-document links to validate.)

Notes

• If new plugin content passes my local LSR test, then it will work for the VPR--with the exception of "internal" links. Remember that links from a plugin doc to Logstash core or another plugin doc can't resolve using the `<> format because the Versioned Plugin Reference has no concept of those internal links.

[karenzone]

@gtback from the infra team specializes in docs tooling work for elastic.co. Looping him in because he might have some ideas that can use some of our existing docs infrastructure to contribute to these goals.

[gtback]

Thanks @karenzone . Happy to chat with @mashhurs about this any time. We can probably automate and set up a process for testing Logstash Plugin PRs before they get into the main docs build (and so you don't have to test them manually). I'm not sure if it will be worth the time invested given the migration to the new docs system, but we can figure that out 😉 .