stackabletech / stackabletech/documentation
Automate reference docs for commandline flags and env vars
Nessuno ha ancora preso questa issue.
- 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
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- 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