Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Validate doc changes (asciidoc formatting, cross-document links) for plugin doc source #42

Open
Tracked by #16841
karenzone opened this issue Mar 6, 2020 · 5 comments
Assignees

Comments

@karenzone
Copy link
Contributor

karenzone commented Mar 6, 2020

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
Copy link
Contributor Author

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

@karenzone karenzone changed the title Validate doc changes (asciidoc formatting, cross-document links) for plugin docs Validate doc changes (asciidoc formatting, cross-document links) for plugin doc source Dec 7, 2021
@karenzone
Copy link
Contributor Author

karenzone commented Mar 31, 2022

@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.

Screen Shot 2022-03-31 at 1 23 28 PM

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
Copy link
Contributor Author

karenzone commented Mar 31, 2022

@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
Copy link
Member

gtback commented Apr 1, 2022

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 😉 .

@mashhurs mashhurs self-assigned this Apr 3, 2022
@karenzone karenzone changed the title Validate doc changes (asciidoc formatting, cross-document links) for plugin doc source Validate doc changes (asciidoc formatting, cross-document links) for plugin doc source - ON HOLD Sep 22, 2022
@karenzone karenzone changed the title Validate doc changes (asciidoc formatting, cross-document links) for plugin doc source - ON HOLD Validate doc changes (asciidoc formatting, cross-document links) for plugin doc source Dec 26, 2024
@karenzone
Copy link
Contributor Author

Update (new issue):

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants