Automate reference docs for commandline flags and env vars

Aberta
#514 1 comentário 0 reações 0 responsáveis Ver no GitHub

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
5/5
Tempo estimado
Mais de uma semana
Facilidade para iniciantes
35/100
Tipo de issue
Funcionalidade
Clareza
Razoavelmente clara
Status de atividade
Estagnada
Stack de tecnologia
rust
Domínio
build-system, documentation

Direção de pesquisa

Revise o workflow existente de geração da referência de CRD e as páginas de referência geradas manualmente para a linha de comando e as variáveis de ambiente do HBase. Em seguida, compare a saída de ajuda dos operadores com a integração de build.rs e do parser clap descrita na issue, incluindo verificar se os subcommands precisam de tratamento separado. Considera-se concluído quando uma abordagem de geração sustentável for escolhida e implementada, produzindo páginas de referência utilizáveis sem listas escritas manualmente de flags e variáveis de ambiente.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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/

Linguagem predominante
CSS
Estrelas
13
Forks
14
Merge médio
4d 8h
PRs com merge (30d)
10

Guia de contribuição

Nenhum guia de contribuição indexado para este repositório

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de stackabletech/documentation

Todas as issues de stackabletech/documentation

Issues semelhantes

Mais issues de Build System

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.