Automate reference docs for commandline flags and env vars

Open
#514 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Stale
Tech stack
rust
Domain
build-system, documentation

Research direction

Review the existing generated CRD reference workflow and the manually generated HBase command-line and environment-variable reference pages. Then compare the operators' help output with the build.rs and clap parser integration described in the issue, including whether subcommands need separate handling. Done means choosing and implementing a maintainable generation approach that produces usable reference pages without hand-written flag and environment-variable lists.

Written by the indexing model from the issue text.

Description

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/

Dominant language
CSS
Stars
13
Forks
14
Avg merge
4d 8h
Merged PRs (30d)
10

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from stackabletech/documentation

All issues in stackabletech/documentation

Similar issues

More Build System issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.