stackabletech / stackabletech/documentation

Automate reference docs for commandline flags and env vars

オープン
#514 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

priority/low
主要言語
CSS
スター
13
フォーク
14
平均マージ
4日 8時間
マージ済み PR(30日)
10

説明

Problem: Currently we have hand written docs in every operator about commandline flags and environment variables read by the operators. This is difficult to maintain and in some places it is already out of date. Like the CRD references, it would be good to generate this to reduce maintenance burden.

Cheapo variant A: dump the help page

The help pages of the operators actually already reference all the flags (obviously) and also most env vars (some would need to be added through clap, that is easy though). We already do this for stackablectl. It isn't pretty, the formatting is actually quite ugly.

By default the help doesn't show help for subcommands. Maybe we have to call each subcommand individually (or maybe we just show the help for run).

Slightly more involved variant B: generate man page, convert to adoc

There is https://github.com/clap-rs/clap/tree/master/clap_mangen to generate man pages from clap.

We could use pandoc to convert the man page to an adoc file:

pandoc -s -t asciidoc example.man -o example.adoc

And use that as our reference page.

This is a bit annoying to implement because the build.rs file has to include the clap parser definition too. Also I am unsure about the pandoc converted adoc page, I am not sure if the styling can be changed or how easily it can be done.

For reference (currently manually generated):
https://docs.stackable.tech/home/stable/hbase/reference/commandline-parameters/
https://docs.stackable.tech/home/stable/hbase/reference/environment-variables/

コントリビューションガイド

このリポジトリのコントリビューションガイドは索引されていません

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

調査の方向性

既存の CRD リファレンス生成ワークフローと、手動で生成されている HBase のコマンドラインおよび環境変数のリファレンスページを確認します。次に、issue で説明されている build.rs と clap パーサーの統合と、operators のヘルプ出力を比較し、subcommands に個別の処理が必要かどうかも確認します。手書きの flag と環境変数の一覧を使わずに利用可能なリファレンスページを生成できる、保守しやすい生成方式を選択して実装すれば完了です。

索引モデルが issue の本文から書いたものです。

評価

技術スタック
rust
領域
build-system, documentation
issue の種類
機能追加
難易度
5/5
見積もり時間
1週間以上
活発さ
停滞
明瞭さ
おおむね明確
初心者へのやさしさ
35/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。