* Generate a tctl reference page
Add a `cli-docs-tctl` Make target and generate the page.
To allow the page to render, make the `tctl edit` help text more
consistent with that of other commands by using a single line for the
resource type/name argument.
This change adds 47 `tctl` commands not present in the current
reference.
Also change the default value of the `tctl recordings download`
`output-dir` flag to the system-independent "." value. Otherwise,
generating this page prints a system-specific file path.
Also make minor modifications to flag, argument, and command
descriptions to be consistent with messaging conventions in the docs.
* CLI ref generator: add arg/flag default overrides
In the CLI reference doc generator, make it possible to override default
argument and flag values. This is necessary when these values are
dynamic and system dependent, e.g., a user's home directory.
Add the `flag_default_overrides` and `arg_default_overrides` fields to
the generator config file. Use these fields to create template functions
that replace default values in a `*kingpin.FlagModel` or
`*kingpin.ArgModel`.
* Add flag default overrides for tctl reference
Configure flags with dynamic values to have hardcoded values in the
reference docs page so there is no need to edit the dynamic argument
logic in the tctl source.
Generated CLI reference docs take their introductory paragraphs from the
app-wide descriptions defined using the `kingpin` library. However, this
approach can make for awkward text, as the in-app descriptions are not
intended for docs pages.
This change modifies the logic for loading config files for generating
CLI reference docs in order to define custom introductions. It enforces
a nonempty introduction field in the config.
There is currently one CLI reference page we generate from the source,
the one for tsh. Edit the tsh reference generator config to include an
introduction.
Tangential changes:
- Pass a loaded config in `updateAppUsageTemplate` so we can define
introductions in tests.
- Print error messages to stdout and exit with an error instead of
panicking. This is because kingpin prints CLI help text to stderr,
which gets redirected to the generated docs page.
The MDX parser encounters errors when parsing square and angle brackets
in argument and flag descriptions, since these look like malformed links
and tags. Escape these characters so generated CLI reference pages
render correctly.
Sort the flag and argument tables of generated CLI docs. Do so
alphabetically by the value of the first column, disregarding non-word
characters and character case.
* CLI reference generator: load default env variables from a YAML file
* - Add the 'sidebar_label' and 'tags' frontmatter fields
- Adjust the template and anyEnvVarsForCmd to prevent listing empty environment variable / flag lists
* Clean up the CLI doc generator
Remove unnecessary intermediate values: pass the unmarshaled YAML data
structure directly from `loadDefaultEnvVars` to `UpdateAppUsageTemplate`
without converting it from a `[][4]string`.
* Improve CLI doc generator error handling
Instead of silently exiting with no error if it is not possible to read
the CLI doc generator config file, print an error message.
If there is no CLI generator config file, skip manual environment
variable additions and print a message. (Not using structured logging
since this will only ever be run manually and in CI.)
---------
Co-authored-by: Aatu Väisänen <aatu.vaisanen.ext@goteleport.com>
* Add a CLI reference generator
See #3568
Add a function to update the kingpin usage template for a CLI
application and print a docs page. As a starting point, includes a
`docs` subcommand in `tsh` to call the function for that tool. By
generating CLI documentation, we can ensure that commmand, argument, and
flag usage information is consistent with the terminal help text for a
given CLI. We can also ensure that all changes to a CLI application are
reflected in the documentation.
As an alternative, we could edit `UpdateAppUsageTemplate` in `lib/utils`
to update the usage template to print an MDX page, e.g., using build
tags to print a docs template instead of the default usage template.
This approach would update all CLI tools at once and use a consistent
approach with minimal changes to each CLI tool. However, using a
separate function to take a `*kingpin.Application` and print a docs page
is more straightforward and explicit, even though it does require
editing each CLI tool to call the function.
One shortcoming of generating the CLI reference docs versus our current
manual approach is that it is non-trivial (and potentially impossible)
to use `kingpin`'s usage API to obtain the value types of the
subcommands, flags, and arguments registered against a
`*kingpin.Application`. We can use flag and argument descriptions and
default values to achieve the same purpose.
Another shortcoming is that `kingpin`'s usage API does not print usage
information for arguments, environment variable, etc. that a CLI looks
up directly from the OS, such as the `TELEPORT_CLUSTER` environment
variable for `tsh`.
* Respond to zmb3 and atburke feedback
**Separate docs generation code from production code.**
Add a separate implementation of `UpdateAppUsageTemplate` that requires
the `docs` build tag. Since all Go-based Teleport CLI tools call
`UpdateAppUsageTemplate`, the `docs` build of the function ensure that
the `help` command for Teleport CLI tools prints a docs page.
This change also adds a `cli-docs-tsh` make target to generate a docs
page for `tsh`.
**Escape pipes in `formatHelp`** to avoid breaking table cells.
* Respond to atburke feedback
- Make the main help description more visible. Assume that the main help
description is not necessarily a complete sentence, adding the text to
the end of the introductory sentence using a colon.
- Add a make rule for running CLI docs generator tests. Use the `-run`
flag since the tests are in a package we already run tests for in
another make rule.
* Respond to zmb3 feedback
- Use Fprintf instead of Buffer.WriteString.
- Use the zero value of bytes.Buffer instead of NewBuffer.
- Rename `.*ToColumns` functions to `.*ToRows` for clarity.
- Use slices.ContainsFunc in anyVisibleFlags.
- Use slices.ContainsFunc in anyEnvVarsForCmd.
- Clean up argsToRows.
- Minor cleanup in TestUpdateAppUsageTemplate.
- Clean up sortCommandsByName (no need to implement sort.Interface).
- Read the docs usage template from disk in UpdateAppUsageTemplate. For
this to work, add the function updateAppUsageTemplate, which takes an
io.Reader, and use separate file paths to pass the io.Reader to the
function in the tests and in UpdateAppUsageTemplate.
- Inline formatFlagForTable and remove unnecessary branching.
- Add an ADDTAGS environment variable to the `test-go-unit` make
target so it's possible to pass arbitrary build tags, e.g., "docs".
STeve (Xin) Huang