stackabletech / stackabletech/documentation
Automate reference docs for commandline flags and env vars
Dieses Issue hat noch niemand übernommen.
- Vorherrschende Sprache
- CSS
- Sterne
- 13
- Forks
- 14
- Ø Merge
- 4 T. 8 Std.
- Gemergte PRs (30 T.)
- 10
Beschreibung
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/
Beitragsleitfaden
Für dieses Repository ist kein Beitragsleitfaden indexiert
Erste Schritte
- Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
- Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
- Forke das Repository und arbeite in einem Branch.
- Öffne einen Pull Request, der die Issue-Nummer nennt.
Rechercherichtung
Überprüfe den bestehenden Workflow zur Generierung der CRD-Referenz sowie die manuell generierten Referenzseiten für die HBase-Befehlszeile und Umgebungsvariablen. Vergleiche anschließend die Ausgabe der Hilfe der Operatoren mit der in diesem Issue beschriebenen Integration von build.rs und dem clap-Parser, einschließlich der Frage, ob Subcommands separat behandelt werden müssen. Als erledigt gilt die Auswahl und Implementierung eines wartbaren Generierungsansatzes, der nutzbare Referenzseiten ohne manuell geschriebene Listen von Flags und Umgebungsvariablen erzeugt.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- rust
- Bereich
- build-system, documentation
- Issue-Typ
- Feature
- Schwierigkeit
- 5/5
- Geschätzter Aufwand
- Über eine Woche
- Aktivitätsstatus
- Veraltet
- Klarheit
- Größtenteils klar
- Anfängerfreundlichkeit
- 35/100