stackabletech / stackabletech/documentation

Automate reference docs for commandline flags and env vars

Ouverte
#514 1 commentaire 0 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

priority/low
Langage dominant
CSS
Étoiles
13
Forks
14
Merge moyen
4 j 8 h
PR mergées (30 j)
10

Description

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/

Guide de contribution

Aucun guide de contribution indexé pour ce dépôt

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Piste de recherche

Examinez le workflow existant de génération de la référence CRD ainsi que les pages de référence générées manuellement pour la ligne de commande et les variables d’environnement de HBase. Comparez ensuite la sortie de l’aide des opérateurs avec l’intégration de build.rs et de l’analyseur clap décrite dans l’issue, notamment pour déterminer si les subcommands nécessitent une gestion séparée. Le travail est considéré comme terminé lorsqu’une approche de génération maintenable est choisie et implémentée afin de produire des pages de référence utilisables sans listes de flags et de variables d’environnement écrites manuellement.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
rust
Domaine
build-system, documentation
Type d'issue
Fonctionnalité
Difficulté
5/5
Temps estimé
Plus d'une semaine
Activité
À l'abandon
Clarté
Plutôt claire
Accessibilité débutants
35/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.