DocsV3: Update plugin docgen tooling to work with new MD files and structure #110
Description
Current stack-versioned plugin docs tooling generates plugin docs for inclusion in the Logstash Reference (LSR). I broke plugin doc generation (for main and 9.0) when I replaced asciidoc source files in the logstash repo with the new MD source files. Tooling is looking for logstash/docs/index.asciidoc, but it's no longer there.
Update:
We have work-arounds that let us generate plugin docs PRs after:
- GH: Add action to build 9.x series plugin docs logstash-docs#1829 + elastic/logstash-docs@dec9b88
- Research: Plugin docgen without docbuild logstash-docs#1839 +Fix yaml format in GH action logstash-docs#1842
The output will still fail docs-ci because of differences between ADOC and MD, but we have output to work with, cutting out several manual steps outlined in https://github.com/elastic/logstash-docs-md/issues/16..
Decisions
- Where should conversion happen? Source? Enrichment? End-of-pipeline?
- When to migrate source content?
- We'll likely need a phased approach (short-term, mid-term, long-term) to deal with complexity and volume. What does that look like?
Considerations
- Need ability to support both MD (for 9.0+) and ASCIIDOC (for 8.x and earlier).
- File location and
Includepath settings are different for 9.0+ and 8.x. - Link format varies between ADOC and MD, and so far, has required manual cleanup
Tooling affected
- LSR plugin docgen:
- Note that tooling for the Versioned Plugin Reference (VPR) is unaffected because it's self-contained. That is, it doesn't rely on any files in the
logstashrepo.
Related and relevant
Requirements
- Stack-versioned docs tooling should be modified to generate plugin docs for
main9.0, and9.xbranches - Stack-versioned docs tooling should maintain existing (or equivalent) functionality to build plugin docs for 8.x series and earlier branches.