From dd368651d6ec38c4def0e5c74010fb00ce96a36f Mon Sep 17 00:00:00 2001 From: Abhinav Gupta Date: Mon, 22 Jul 2024 18:43:37 -0700 Subject: [PATCH] doc: Move CLI Reference to subsection (#280) Per feedback from someone navigating the documentation, since all other top-level sections are just listing, it's confusing that this one is not. Move CLI reference into a page nested under the CLI section. Resolves #276 --- doc/hooks/cliref.py | 2 +- doc/includes/cli-shorthands.md | 58 +++++++++++++++++----------------- doc/mkdocs.yml | 1 + doc/src/cli/index.md | 12 ++++--- doc/src/cli/reference.md | 10 ++++++ doc/src/guide/index.md | 3 +- doc/src/index.md | 8 ++--- dumpmd.go | 2 +- 8 files changed, 55 insertions(+), 41 deletions(-) create mode 100644 doc/src/cli/reference.md diff --git a/doc/hooks/cliref.py b/doc/hooks/cliref.py index 79f2edf4..492fd043 100644 --- a/doc/hooks/cliref.py +++ b/doc/hooks/cliref.py @@ -7,7 +7,7 @@ from mkdocs.structure.files import Files -_CLI_PAGE = "cli/index.md" +_CLI_PAGE = "cli/reference.md" _cmd_re = re.compile(r"\$\$([^$]+)\$\$") diff --git a/doc/includes/cli-shorthands.md b/doc/includes/cli-shorthands.md index 1b85e1d8..c243d1c8 100644 --- a/doc/includes/cli-shorthands.md +++ b/doc/includes/cli-shorthands.md @@ -1,31 +1,31 @@ | **Shorthand** | **Long form** | | --- | --- | -| gs bc | [gs branch create](/cli/index.md#gs-branch-create) | -| gs bco | [gs branch checkout](/cli/index.md#gs-branch-checkout) | -| gs bd | [gs branch delete](/cli/index.md#gs-branch-delete) | -| gs be | [gs branch edit](/cli/index.md#gs-branch-edit) | -| gs bfo | [gs branch fold](/cli/index.md#gs-branch-fold) | -| gs bon | [gs branch onto](/cli/index.md#gs-branch-onto) | -| gs br | [gs branch restack](/cli/index.md#gs-branch-restack) | -| gs brn | [gs branch rename](/cli/index.md#gs-branch-rename) | -| gs bs | [gs branch submit](/cli/index.md#gs-branch-submit) | -| gs bsp | [gs branch split](/cli/index.md#gs-branch-split) | -| gs btr | [gs branch track](/cli/index.md#gs-branch-track) | -| gs buntr | [gs branch untrack](/cli/index.md#gs-branch-untrack) | -| gs ca | [gs commit amend](/cli/index.md#gs-commit-amend) | -| gs cc | [gs commit create](/cli/index.md#gs-commit-create) | -| gs csp | [gs commit split](/cli/index.md#gs-commit-split) | -| gs dse | [gs downstack edit](/cli/index.md#gs-downstack-edit) | -| gs dss | [gs downstack submit](/cli/index.md#gs-downstack-submit) | -| gs ll | [gs log long](/cli/index.md#gs-log-long) | -| gs ls | [gs log short](/cli/index.md#gs-log-short) | -| gs rba | [gs rebase abort](/cli/index.md#gs-rebase-abort) | -| gs rbc | [gs rebase continue](/cli/index.md#gs-rebase-continue) | -| gs ri | [gs repo init](/cli/index.md#gs-repo-init) | -| gs rs | [gs repo sync](/cli/index.md#gs-repo-sync) | -| gs se | [gs stack edit](/cli/index.md#gs-stack-edit) | -| gs sr | [gs stack restack](/cli/index.md#gs-stack-restack) | -| gs ss | [gs stack submit](/cli/index.md#gs-stack-submit) | -| gs uso | [gs upstack onto](/cli/index.md#gs-upstack-onto) | -| gs usr | [gs upstack restack](/cli/index.md#gs-upstack-restack) | -| gs uss | [gs upstack submit](/cli/index.md#gs-upstack-submit) | +| gs bc | [gs branch create](/cli/reference.md#gs-branch-create) | +| gs bco | [gs branch checkout](/cli/reference.md#gs-branch-checkout) | +| gs bd | [gs branch delete](/cli/reference.md#gs-branch-delete) | +| gs be | [gs branch edit](/cli/reference.md#gs-branch-edit) | +| gs bfo | [gs branch fold](/cli/reference.md#gs-branch-fold) | +| gs bon | [gs branch onto](/cli/reference.md#gs-branch-onto) | +| gs br | [gs branch restack](/cli/reference.md#gs-branch-restack) | +| gs brn | [gs branch rename](/cli/reference.md#gs-branch-rename) | +| gs bs | [gs branch submit](/cli/reference.md#gs-branch-submit) | +| gs bsp | [gs branch split](/cli/reference.md#gs-branch-split) | +| gs btr | [gs branch track](/cli/reference.md#gs-branch-track) | +| gs buntr | [gs branch untrack](/cli/reference.md#gs-branch-untrack) | +| gs ca | [gs commit amend](/cli/reference.md#gs-commit-amend) | +| gs cc | [gs commit create](/cli/reference.md#gs-commit-create) | +| gs csp | [gs commit split](/cli/reference.md#gs-commit-split) | +| gs dse | [gs downstack edit](/cli/reference.md#gs-downstack-edit) | +| gs dss | [gs downstack submit](/cli/reference.md#gs-downstack-submit) | +| gs ll | [gs log long](/cli/reference.md#gs-log-long) | +| gs ls | [gs log short](/cli/reference.md#gs-log-short) | +| gs rba | [gs rebase abort](/cli/reference.md#gs-rebase-abort) | +| gs rbc | [gs rebase continue](/cli/reference.md#gs-rebase-continue) | +| gs ri | [gs repo init](/cli/reference.md#gs-repo-init) | +| gs rs | [gs repo sync](/cli/reference.md#gs-repo-sync) | +| gs se | [gs stack edit](/cli/reference.md#gs-stack-edit) | +| gs sr | [gs stack restack](/cli/reference.md#gs-stack-restack) | +| gs ss | [gs stack submit](/cli/reference.md#gs-stack-submit) | +| gs uso | [gs upstack onto](/cli/reference.md#gs-upstack-onto) | +| gs usr | [gs upstack restack](/cli/reference.md#gs-upstack-restack) | +| gs uss | [gs upstack submit](/cli/reference.md#gs-upstack-submit) | diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml index 335e093b..906f085e 100644 --- a/doc/mkdocs.yml +++ b/doc/mkdocs.yml @@ -109,6 +109,7 @@ nav: - setup/shell.md - CLI: - cli/index.md + - cli/reference.md - cli/shorthand.md - how-to.md - FAQ: faq.md diff --git a/doc/src/cli/index.md b/doc/src/cli/index.md index 5e1b5098..a23b0fa7 100644 --- a/doc/src/cli/index.md +++ b/doc/src/cli/index.md @@ -1,10 +1,12 @@ --- -icon: material/console +icon: material/console-line +template: templates/index_page.html +hide: [toc] description: >- - Comprehensive list of all available commands and options - for the git-spice CLI. + Learn about the specifics of the git-spice CLI. --- -# CLI Reference +# CLI ---8<-- "cli-reference.md" +The git-spice CLI is delivered as the command `gs`. +Explore the [complete list of available commands here](reference.md). diff --git a/doc/src/cli/reference.md b/doc/src/cli/reference.md new file mode 100644 index 00000000..5e1b5098 --- /dev/null +++ b/doc/src/cli/reference.md @@ -0,0 +1,10 @@ +--- +icon: material/console +description: >- + Comprehensive list of all available commands and options + for the git-spice CLI. +--- + +# CLI Reference + +--8<-- "cli-reference.md" diff --git a/doc/src/guide/index.md b/doc/src/guide/index.md index 54856f24..c6f1ad69 100644 --- a/doc/src/guide/index.md +++ b/doc/src/guide/index.md @@ -9,4 +9,5 @@ description: >- The User Guide covers the features of git-spice in more detail. -For a list of all available commands, see the [Command Reference](../cli/index.md). +For a list of all available commands, +see the [Command Reference](../cli/reference.md). diff --git a/doc/src/index.md b/doc/src/index.md index a2087b94..c026d4b3 100644 --- a/doc/src/index.md +++ b/doc/src/index.md @@ -83,10 +83,10 @@ $ gs repo sync Create GitHub Pull Requests from your stack with a single command. git-spice can create - [a PR for the current branch](cli/index.md#gs-branch-submit), - [PRs for the entire stack](cli/index.md#gs-stack-submit), or - [parts of](cli/index.md#gs-upstack-submit) - [the stack](cli/index.md#gs-downstack-submit). + [a PR for the current branch](cli/reference.md#gs-branch-submit), + [PRs for the entire stack](cli/reference.md#gs-stack-submit), or + [parts of](cli/reference.md#gs-upstack-submit) + [the stack](cli/reference.md#gs-downstack-submit). If a branch already has a PR, git-spice will update it. If a PR is merged, git-spice will automatically restack branches that depend on it. diff --git a/dumpmd.go b/dumpmd.go index 8f2bcdc1..18246098 100644 --- a/dumpmd.go +++ b/dumpmd.go @@ -51,7 +51,7 @@ func dumpShorthands(w io.Writer, shorts shorthands) { t.appendHeaders("Shorthand", "Long form") for _, key := range keys { cmd := cmdFullName(shorts[key].Command) - link := fmt.Sprintf("[%v](/cli/index.md#%v)", cmd, strings.ReplaceAll(cmd, " ", "-")) + link := fmt.Sprintf("[%v](/cli/reference.md#%v)", cmd, strings.ReplaceAll(cmd, " ", "-")) t.addRow("gs "+key, link) } t.dump(w)