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

@@ -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"\$\$([^$]+)\$\$")
 
 

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) |

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

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).

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"

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).

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.

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)