DocsV3: Update plugin docgen tooling to work with new MD files and structure
まだ誰も着手していません。
評価
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 初心者へのやさしさ
- 25/100
- issue の種類
- バグ
- 明瞭さ
- 説明が足りない
- 活発さ
- 停滞
- 技術スタック
- github-actions, ruby
調査の方向性
plugindocs.rb と reference_docs.yml GitHub Action から始め、main/9.x と 8.x 以前のブランチでプラグインのドキュメントがどのように生成されるかを比較します。現在の動作について、リンクされている workaround と関連する issue を確認します。新しい MD ベースのブランチでツールがプラグインのドキュメントを生成し、古い ASCIIDOC ブランチに対する同等のサポートも維持できれば完了です。
索引モデルが issue の本文から書いたものです。
説明
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:
- 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
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.
- 主要言語
- Ruby
- スター
- 4
- フォーク
- 12
- PR マージ指標
- 30日以内にマージされた PR はありません
環境構築
このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
elastic/docs-tools のほかの issue
-
VPR
難易度 4/5 3〜5日 初心者へのやさしさ 42/100
elastic/docs-tools#109 · コメント 1 件 ·
-
Missing plugin VPR docs between placeholder generation and last commit date.再び着手できるかも @mashhurs が 1116 日前に担当しましたが、オープン中のプルリクエストはありません。 オープン
elastic/docs-tools#100 · コメント 2 件 · 担当者 1 名 ·
-
VPR: Revisit allowing a non-standard landing page (use case: new integrations)再び着手できるかも このイシューのプルリクエストはマージされずにクローズされました。 オープンVPR
難易度 5/5 1週間以上 初心者へのやさしさ 25/100
elastic/docs-tools#89 · コメント 1 件 ·
-
VPR
難易度 5/5 1週間以上 初心者へのやさしさ 25/100
elastic/docs-tools#88 ·
-
enhancement
難易度 4/5 3〜5日 初心者へのやさしさ 35/100
elastic/docs-tools#82 ·
elastic/docs-tools の issue をすべて見る
似ている issue
-
bug needs-triaging
難易度 2/5 1〜3時間 初心者へのやさしさ 70/100
SeleniumHQ/seleniumhq.github.io#2952 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
hashicorp/homebrew-tap#433 ·
-
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
メンテナーはふだん 8 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
メンテナーはふだん 1 日以内に返信
-
難易度 1/5 1時間未満 初心者へのやさしさ 62/100
TheOdinProject/curriculum#31509 ·
メンテナーはふだん 1 日以内に返信