diff --git a/doc/development/documentation/styleguide/cli.md b/doc/development/documentation/styleguide/cli.md new file mode 100644 index 0000000000000000000000000000000000000000..9b117c545123b8061e6f5516e7237f8a24309fb4 --- /dev/null +++ b/doc/development/documentation/styleguide/cli.md @@ -0,0 +1,47 @@ +--- +stage: none +group: unassigned +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +description: Writing styles, markup, formatting, and other standards for GitLab Documentation. +title: CLI Documentation Style Guide +--- + +This document defines style standards for documentation presented in GitLab products through the command line and builds on the +general [Documentation Style Guide](_index.md). + +## Gitaly and Praefect + +Gitaly and Praefect define expectations for help text and command strings in the +[Gitaly Help text style guide](https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/help_text_style_guide.md). + +## GitLab CLI (`glab`) + +The documentation and CLI help text for `glab` are both rendered from the backend files for the commands. +Each output uses a slightly different rendering engine. + +### Backticks + +To render backticks in displayed text, such as a command's `Long:` description, wrap the +description text in a `heredoc`, like this, and use `%[1]s` instead of backticks: + +```go +Long: heredoc.Docf(`Description text with %[1]sbackticks%[1]s`, "`"), +``` + +## Render `glab` documentation locally + +Most commands and sub-commands for the GitLab CLI are located in the [`internal/commands/` folder](https://gitlab.com/gitlab-org/cli/-/tree/main/internal/commands) +of the `cli` project. The `docs/source/` folder contains the rendered HTML version of the documentation. +To see the CLI version of the documentation, run the command you want to see, and append `--help` to the end, +like this: + +```shell +glab issue list --help +``` + +To regenerate the documentation from the root of the `cli` repository, run the command `make gen-docs`. + +## Related topics + +- [UI text](https://design.gitlab.com/content/ui-text/) from GitLab Design System. +- [Command Line Interface Guidelines](https://clig.dev).