mirror of
https://github.com/gravitational/teleport.git
synced 2026-09-19 11:00:37 +08:00
Paul Gottschling
f104ab66e4
* 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".
92 lines
2.0 KiB
Cheetah
92 lines
2.0 KiB
Cheetah
{{define "FormatCommand" -}}
|
|
{{if .Flags|AnyVisibleFlags}}{{if .FlagSummary }} {{.FlagSummary}}{{end}}{{end -}}
|
|
{{range .Args}}{{if not .Hidden}} {{ .|FormatUsageArg}}{{end}}{{end -}}
|
|
{{end -}}
|
|
|
|
{{ define "FormatCommands" -}}
|
|
{{$appName := .Name -}}
|
|
{{range .FlattenedCommands|SortCommandsByName -}}
|
|
{{if not .Hidden -}}
|
|
## {{$appName}} {{.FullCommand}}
|
|
|
|
{{.Help|Wrap 0 }}
|
|
Usage:
|
|
|
|
```code
|
|
$ {{$appName}} {{.FullCommand}}{{template "FormatCommand" .}}
|
|
```
|
|
|
|
{{if AnyEnvVarsForCmd .Args .Flags -}}
|
|
Environment variables:
|
|
|
|
|Variable|Default|Description|
|
|
|---|---|---|
|
|
{{- EnvVarsToRows .Args .Flags|FormatThreeColMarkdownTable}}
|
|
|
|
{{end -}}
|
|
|
|
{{ if .Flags|AnyVisibleFlags -}}
|
|
Flags:
|
|
|
|
|Flag|Default|Description|
|
|
|---|---|---|
|
|
{{- .Flags|FlagsToRows|FormatThreeColMarkdownTable }}
|
|
|
|
{{end -}}
|
|
{{ if .Args -}}
|
|
Arguments:
|
|
|
|
|Argument|Default|Description|
|
|
|---|---|---|
|
|
{{- .Args|ArgsToRows|FormatThreeColMarkdownTable }}
|
|
|
|
{{end -}}
|
|
{{end -}}
|
|
{{end -}}
|
|
{{end -}}
|
|
|
|
{{define "FormatUsage" -}}
|
|
```code
|
|
$ {{.Name}}{{template "FormatCommand" .}}{{if .Commands}} <command> [<args> ...]{{end}}
|
|
```
|
|
|
|
{{end -}}
|
|
---
|
|
title: {{.App.Name}} Reference
|
|
description: Provides a comprehensive list of commands, arguments, and flags for {{.App.Name}}.
|
|
---
|
|
|
|
This guide provides a comprehensive list of commands, arguments, and flags for
|
|
{{.App.Name}}: {{ if .App.Help -}}
|
|
{{- .App.Help|Wrap 0 }}
|
|
{{ end -}}
|
|
|
|
{{template "FormatUsage" .App -}}
|
|
{{if .Context.Flags -}}
|
|
Global flags:
|
|
|
|
|Flag|Default|Description|
|
|
|---|---|---|
|
|
{{- .Context.Flags|FlagsToRows|FormatThreeColMarkdownTable}}
|
|
|
|
{{end -}}
|
|
{{if AnyEnvVarsForCmd .Context.Args .Context.Flags -}}
|
|
Global environment variables:
|
|
|
|
|Variable|Default|Description|
|
|
|---|---|---|
|
|
{{- EnvVarsToRows .Context.Args .Context.Flags|FormatThreeColMarkdownTable}}
|
|
|
|
{{end -}}
|
|
{{if .Context.Args -}}
|
|
Arguments:
|
|
|
|
|Argument|Default|Description|
|
|
|---|---|---|
|
|
{{- .Context.Args|ArgsToRows|FormatThreeColMarkdownTable}}
|
|
|
|
{{end -}}
|
|
{{if .App.Commands -}}
|
|
{{template "FormatCommands" .App -}}
|
|
{{end -}}
|