stackabletech / stackabletech/documentation

Automate reference docs for commandline flags and env vars

Aperta
#514 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

priority/low
Lingua principale
CSS
Stelle
13
Fork
14
Merge medio
4g 8h
PR unite (30g)
10

Descrizione

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/

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Direzione di ricerca

Esamina il workflow esistente per la generazione del riferimento CRD e le pagine di riferimento generate manualmente per la riga di comando e le variabili d’ambiente di HBase. Confronta quindi l’output dell’help degli operatori con l’integrazione di build.rs e del parser clap descritta nell’issue, verificando anche se i subcommands richiedano una gestione separata. Il lavoro è considerato completato quando viene scelto e implementato un approccio di generazione manutenibile che produca pagine di riferimento utilizzabili senza elenchi scritti manualmente di flag e variabili d’ambiente.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
rust
Ambito
build-system, documentation
Tipo di issue
Funzionalità
Difficoltà
5/5
Tempo stimato
Più di una settimana
Stato di attività
Ferma
Chiarezza
Abbastanza chiara
Idoneità per principianti
35/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.