From 816cdc0cd4506e820641f35602074d085a2f4b04 Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Mon, 8 Sep 2025 12:41:54 -0700 Subject: [PATCH 1/8] Stub out a CLI-specific style guide page Start by putting the skeleton in place. Link to the style decisions made in the Gitaly and Praefect projects, and to a good external resource we're aware of. --- .../documentation/styleguide/cli.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 doc/development/documentation/styleguide/cli.md diff --git a/doc/development/documentation/styleguide/cli.md b/doc/development/documentation/styleguide/cli.md new file mode 100644 index 00000000000000..c67eef9d318ddd --- /dev/null +++ b/doc/development/documentation/styleguide/cli.md @@ -0,0 +1,22 @@ +--- +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: Documentation Style Guide +--- + +This document defines standards for GitLab documentation presented through the CLI. It captures +styling decisions that are unique to text-based environments. + +## 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`) + +## Related topics + +- [UI text](https://design.gitlab.com/content/ui-text/) from GitLab Design System. +- [Command Line Interface Guidelines](https://clig.dev). -- GitLab From ece9452e9b81e6b0a37b249cfa4782f883530aee Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Mon, 8 Sep 2025 12:57:18 -0700 Subject: [PATCH 2/8] Propose a stub for CLI documentation I'm not sure this is the right approach, but I have an increasing amount of colloquial knowledge in my head, with no place to put it. --- doc/development/documentation/styleguide/cli.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/doc/development/documentation/styleguide/cli.md b/doc/development/documentation/styleguide/cli.md index c67eef9d318ddd..50338b0ba93a52 100644 --- a/doc/development/documentation/styleguide/cli.md +++ b/doc/development/documentation/styleguide/cli.md @@ -16,6 +16,22 @@ Gitaly and Praefect define expectations for help text and command strings in the ## 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. + +## Update `glab` documentation + +Most commands and sub-commands for the GitLab CLI are located in the [`internal/commands/` folder](https://gitlab.com/gitlab-org/cli/) +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. -- GitLab From 6bdcda06433a602b9c7918882bd9fd51f8d1ef84 Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Mon, 8 Sep 2025 13:05:23 -0700 Subject: [PATCH 3/8] Apply 1 suggestion(s) to 1 file(s) Co-authored-by: GitLab Duo --- doc/development/documentation/styleguide/cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/documentation/styleguide/cli.md b/doc/development/documentation/styleguide/cli.md index 50338b0ba93a52..c9aaffac010565 100644 --- a/doc/development/documentation/styleguide/cli.md +++ b/doc/development/documentation/styleguide/cli.md @@ -21,7 +21,7 @@ Each output uses a slightly different rendering engine. ## Update `glab` documentation -Most commands and sub-commands for the GitLab CLI are located in the [`internal/commands/` folder](https://gitlab.com/gitlab-org/cli/) +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: -- GitLab From 488ba8f2fe0e2504aefc71c4145809c2ea3cc6fe Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Mon, 8 Sep 2025 13:09:32 -0700 Subject: [PATCH 4/8] Apply 1 suggestion(s) to 1 file(s) Co-authored-by: GitLab Duo --- doc/development/documentation/styleguide/cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/documentation/styleguide/cli.md b/doc/development/documentation/styleguide/cli.md index c9aaffac010565..153f9420b81efa 100644 --- a/doc/development/documentation/styleguide/cli.md +++ b/doc/development/documentation/styleguide/cli.md @@ -3,7 +3,7 @@ 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: Documentation Style Guide +title: CLI Documentation Style Guide --- This document defines standards for GitLab documentation presented through the CLI. It captures -- GitLab From 5ad2db39d434c6eb92291deb313bc24d2eb38886 Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Tue, 9 Sep 2025 08:25:20 -0700 Subject: [PATCH 5/8] Apply 1 suggestion(s) to 1 file(s) Co-authored-by: Evan Read --- doc/development/documentation/styleguide/cli.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/development/documentation/styleguide/cli.md b/doc/development/documentation/styleguide/cli.md index 153f9420b81efa..82a28fbb163b58 100644 --- a/doc/development/documentation/styleguide/cli.md +++ b/doc/development/documentation/styleguide/cli.md @@ -6,8 +6,8 @@ description: Writing styles, markup, formatting, and other standards for GitLab title: CLI Documentation Style Guide --- -This document defines standards for GitLab documentation presented through the CLI. It captures -styling decisions that are unique to text-based environments. +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 -- GitLab From b6e2ff1afd9116ce1d5914fc9ddf5de5c5e2252e Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Wed, 10 Sep 2025 16:14:25 -0700 Subject: [PATCH 6/8] Apply 1 suggestion(s) to 1 file(s) --- doc/development/documentation/styleguide/cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/documentation/styleguide/cli.md b/doc/development/documentation/styleguide/cli.md index 82a28fbb163b58..72af1fb8eb172b 100644 --- a/doc/development/documentation/styleguide/cli.md +++ b/doc/development/documentation/styleguide/cli.md @@ -19,7 +19,7 @@ Gitaly and Praefect define expectations for help text and command strings in the 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. -## Update `glab` documentation +## 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. -- GitLab From a79670e326a7a3f9b420cd5261c581a271582994 Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Wed, 10 Sep 2025 16:15:37 -0700 Subject: [PATCH 7/8] Apply 1 suggestion(s) to 1 file(s) --- doc/development/documentation/styleguide/cli.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/development/documentation/styleguide/cli.md b/doc/development/documentation/styleguide/cli.md index 72af1fb8eb172b..f295523ce02d7a 100644 --- a/doc/development/documentation/styleguide/cli.md +++ b/doc/development/documentation/styleguide/cli.md @@ -19,6 +19,15 @@ Gitaly and Praefect define expectations for help text and command strings in the 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: + +```go +Long: heredoc.Docf(`Description text with %[1]backticks%[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) -- GitLab From b861ec361e7f9ea65ae85b4b740188abdb181af6 Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Wed, 17 Sep 2025 09:10:06 -0700 Subject: [PATCH 8/8] Apply 1 suggestion(s) to 1 file(s) --- doc/development/documentation/styleguide/cli.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/development/documentation/styleguide/cli.md b/doc/development/documentation/styleguide/cli.md index f295523ce02d7a..9b117c545123b8 100644 --- a/doc/development/documentation/styleguide/cli.md +++ b/doc/development/documentation/styleguide/cli.md @@ -22,10 +22,10 @@ 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: +description text in a `heredoc`, like this, and use `%[1]s` instead of backticks: ```go -Long: heredoc.Docf(`Description text with %[1]backticks%[1]s`, "`"), +Long: heredoc.Docf(`Description text with %[1]sbackticks%[1]s`, "`"), ``` ## Render `glab` documentation locally -- GitLab