DocsV3: Update plugin docgen tooling to work with new MD files and structure
- Dominant language
- Ruby
- Stars
- 4
- Forks
- 12
- PR merge metrics
- No merged PRs in 30d
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](https://github.com/elastic/logstash/pull/17289) in the `logstash` repo with the new MD source files. Tooling is looking for `logstash/docs/index.asciidoc`, but it's no longer there.
[Line `1574 Can't find --doc /home/runner/work/logstash-docs/logstash-docs/logstash/docs/index.asciidoc`](https://github.com/elastic/logstash-docs/actions/runs/13928870150/job/38980588712)
**Update:**
We have work-arounds that let us generate plugin docs PRs after:
- https://github.com/elastic/logstash-docs/pull/1829 + https://github.com/elastic/logstash-docs/commit/dec9b880823c00134e8a1dfdf0d072b806451f5b
- https://github.com/elastic/logstash-docs/pull/1839 +https://github.com/elastic/logstash-docs/pull/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 `Include` path 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:
- https://github.com/elastic/docs-tools/blob/main/plugindocs.rb
- [GitHub action in `logstash-docs`](https://github.com/elastic/logstash-docs/blob/main/.github/workflows/reference_docs.yml)
- Note that [tooling](https://github.com/elastic/docs-tools/blob/main/versioned_plugins.rb) for the Versioned Plugin Reference (VPR) is unaffected because it's self-contained. That is, it doesn't rely on any files in the `logstash` repo.
#### Related and relevant
- https://github.com/elastic/logstash-docs/pull/1817
#### Requirements
- [ ] Stack-versioned docs tooling should be modified to generate plugin docs for `main` `9.0`, and `9.x` branches
- [ ] Stack-versioned docs tooling should maintain existing (or equivalent) functionality to build plugin docs for 8.x series and earlier branches.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.