Skip to content

Conversation

@bmorelli25
Copy link
Member

@bmorelli25 bmorelli25 commented Mar 14, 2025

Why

As a part of our migration to Elastic Docs V3, we need to single-source the LSR docs from this repo. Currently, in the asciidoc system, the LSR docs are built from the logstash repo with this repo set up as a dependency. This PR moves the relevant documentation required to build the LSR docs from the logstash repo to this repo.

What this PR does

  1. Copies the docs/include dir from elastic/logstash to this repo under docs/plugins/. The final dirpath is docs/plugins/include.

  2. Copies the docs/static/core-plugins dir from elastic/logstash to this repo under docs/plugins. The final dirpath is docs/plugins/static/core-plugins/.

  3. Finds and replaces:
    Find: ../../../../logstash/docs/include
    Replace: ../include

  4. Finds and replaces:
    Find: ../../../logstash/docs/static/
    Replace:./static/

  5. Finds and replaces:
    Find: ../../include
    Replace: ../../../include

Run with Asciidoc

$GIT_HOME/docs/build_docs --doc $GIT_HOME/logstash-docs/docs/plugins/index.asciidoc --chunk 1

Run with adoc-to-md

  1. Check out this branch.
  2. Update run.sh to:
/scripts/build_docs.pl --in_standard_docker --doc doc/logstash-docs/docs/plugins/index.asciidoc --chunk 1 --open --out out/md_docs

@karenzone karenzone added the LSR label Mar 17, 2025
Copy link
Contributor

@karenzone karenzone left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this work, Brandon. Is there any value to my generating updated docs for main so that we have the latest content in this PR?

Any updated plugin docs for main and 9.0 will need to have include_path: updated in the generated output PR (because that value is set in the logstash-plugins source doc.
For example: https://github.com/logstash-plugins/logstash-input-elasticsearch/blob/main/docs/index.asciidoc?plain=1#L11)

Another candidate for docs tooling later, and an easy manual fix for now.

@karenzone
Copy link
Contributor

FYI: @robbavey @jsvd

@karenzone
Copy link
Contributor

FYI @bmorelli25: Please don't backport to 9.0.
The [gemfile.lock.release](https://github.com/elastic/logstash/blob/9.0/Gemfile.jruby-3.1.lock.release) for each branch determines which plugin versions are appropriate for each release.

Does it make sense for us to generate and merge 9.0 plugin updates, and then migrate everything then?

Copy link
Contributor

@karenzone karenzone left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!
We're already in a place where we can't build stack-versioned plugin docs for main and 9.0 due to file changes/dependencies in logstash repo, so no worries about breaking capabilities.

IMPORTANT: DO NOT BACKPORT to 9.0 (related to gemlock file dependencies). Let's discuss.

@karenzone karenzone merged commit 2da5f3c into elastic:main Mar 20, 2025
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants