Automate reference docs for commandline flags and env vars

Abierto
#514 1 comentario 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
rust
Área
build-system, documentation

Línea de trabajo

Revisa el flujo de trabajo existente para generar la referencia de CRD y las páginas de referencia generadas manualmente para la línea de comandos y las variables de entorno de HBase. Después, compara la salida de ayuda de los operadores con la integración de build.rs y del analizador clap descrita en el issue, incluido si los subcommands necesitan un tratamiento separado. Se considera terminado cuando se haya elegido e implementado un enfoque de generación mantenible que produzca páginas de referencia utilizables sin listas de flags y variables de entorno escritas manualmente.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

priority/low

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/

Lenguaje dominante
CSS
Estrellas
13
Forks
14
Merge medio
4 d 8 h
PR fusionados (30 d)
10

Guía de contribución

No hay ninguna guía de contribución indexada para este repositorio

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de stackabletech/documentation

Todos los issues de stackabletech/documentation

Issues similares

Más issues de Build System

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.