generate and check documentation (#128)

should
- close #124 

## description
as can be seen with
ab1f515,
the CI picks up the bug and
[fails](https://github.com/amtoine/nu-git-manager/actions/runs/7090916798/job/19298927027?pr=128)
:ok_hand:

:point_right: the [new
documentation](https://github.com/amtoine/nu-git-manager/blob/doc/docs/index.md)
and the mentions in the README
[here](https://github.com/amtoine/nu-git-manager/tree/doc?tab=readme-ov-file#gear-usage-toc)
and
[there](https://github.com/amtoine/nu-git-manager/tree/doc?tab=readme-ov-file#pray-getting-help-toc)
:+1:

> **Note**
> the `docs/` directory has been fully generated automatically

.github/workflows/check-documentation.yml

@@ -0,0 +1,34 @@
+name: Checking the documentation
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened]
+  push:
+    branches:
+      - main
+      - nightly
+
+jobs:
+  check-merge:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checking out repository
+        uses: actions/checkout@v3
+
+      - uses: hustcer/[email protected]
+        with:
+          version: "0.87.0"
+
+      - name: Check the documentation
+        shell: nu {0}
+        run: |
+          nu --commands $"
+            use ($env.PWD)/toolkit.nu
+            toolkit doc
+            if not \(git status --short | lines | is-empty\) {
+              error make --unspanned {
+                msg: $'status is non-empty: \(git status --short | lines\)'
+              }
+            }
+          "

README.md

@@ -54,36 +54,21 @@ nupm install --path --force nu-git-manager
 
 ## :gear: usage [[toc](#table-of-content)]
 in your `config.nu` you can add the following to load `nu-git-manager` modules:
-```nu
+```nushell
 # load the main `gm` command
 use nu-git-manager *
 
 # the following are non-essential modules
-use nu-git-manager-sugar git                # augment Git with custom commands
-use nu-git-manager-sugar gh                 # load commands to interact with *GitHub*
-use nu-git-manager-sugar gist               # load commands to interact with *GitHub* gists
+use nu-git-manager-sugar extra *              # augment `gm` with additional commands
 ```
 
+> **Note**  
+> please have a look at the [documentation of NGM](./docs/index.md) for more modules and commands
+
 then you have access to the whole `nu-git-manager` suite :partying_face:
 
 ### :pray: getting help [[toc](#table-of-content)]
-do not hesitate to run one of the following to have more information about what `nu-git-manager` has to offer :thumbsup:
-```nu
-help gm
-# or
-gm
-```
-```nu
-help modules git
-```
-```nu
-help modules gh
-```
-```nu
-help modules gist
-# or
-gist
-```
+please have a look at the [documentation of NGM](./docs/index.md)
 
 ## :exclamation: some ideas of advanced (?) usage [[toc](#table-of-content)]
 everytime i open a terminal, i use [Tmux] to manage sessions, switch between them, detach and reattach, quite a ***BLAZZINGLY FAST*** workflow for my taste :smirk:

docs/index.md

@@ -0,0 +1,30 @@
+## Modules
+- [`nu-git-manager`](./nu-git-manager/index.md)
+- [`nu-git-manager-sugar`](./nu-git-manager-sugar/index.md)
+
+## Commands
+- [`gm`](nu-git-manager/gm.md)
+- [`gm clean`](nu-git-manager/gm-clean.md)
+- [`gm clone`](nu-git-manager/gm-clone.md)
+- [`gm list`](nu-git-manager/gm-list.md)
+- [`gm remove`](nu-git-manager/gm-remove.md)
+- [`gm squash-forks`](nu-git-manager/gm-squash-forks.md)
+- [`gm status`](nu-git-manager/gm-status.md)
+- [`gm update-cache`](nu-git-manager/gm-update-cache.md)
+- [`gm report`](nu-git-manager-sugar/extra/gm-report.md)
+- [`gm repo branch interactive-delete`](nu-git-manager-sugar/git/gm-repo-branch-interactive-delete.md)
+- [`gm repo branch wipe`](nu-git-manager-sugar/git/gm-repo-branch-wipe.md)
+- [`gm repo branches`](nu-git-manager-sugar/git/gm-repo-branches.md)
+- [`gm repo compare`](nu-git-manager-sugar/git/gm-repo-compare.md)
+- [`gm repo fetch branch`](nu-git-manager-sugar/git/gm-repo-fetch-branch.md)
+- [`gm repo get commit`](nu-git-manager-sugar/git/gm-repo-get-commit.md)
+- [`gm repo goto root`](nu-git-manager-sugar/git/gm-repo-goto-root.md)
+- [`gm repo is-ancestor`](nu-git-manager-sugar/git/gm-repo-is-ancestor.md)
+- [`gm repo ls`](nu-git-manager-sugar/git/gm-repo-ls.md)
+- [`gm repo remote list`](nu-git-manager-sugar/git/gm-repo-remote-list.md)
+- [`gm repo switch`](nu-git-manager-sugar/git/gm-repo-switch.md)
+- [`setup`](nu-git-manager-sugar/git/prompt/setup.md)
+- [`gm gh pr checkout`](nu-git-manager-sugar/github/gm-gh-pr-checkout.md)
+- [`gm gh query-api`](nu-git-manager-sugar/github/gm-gh-query-api.md)
+- [`gm gh query-releases`](nu-git-manager-sugar/github/gm-gh-query-releases.md)
+- [`gm gh query-user`](nu-git-manager-sugar/github/gm-gh-query-user.md)

docs/nu-git-manager-sugar/extra/gm-report.md

@@ -0,0 +1,13 @@
+# `nu-git-manager-sugar extra gm report`
+## Description
+get a full report about the local store of repositories
+
+
+
+## Parameters
+
+
+## Signatures
+| input     | output                                                                                                                                                                          |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `nothing` | `table<name: string, branch: string, remote: string, tag: string, index: int, ignored: int, conflicts: int, ahead: int, behind: int, worktree: int, stashes: int, clean: bool>` |

docs/nu-git-manager-sugar/extra/index.md

@@ -0,0 +1,6 @@
+# Module `nu-git-manager-sugar extra`
+## Description
+
+
+## Commands
+- [`gm report`](gm-report.md)

docs/nu-git-manager-sugar/git/gm-repo-branch-interactive-delete.md

@@ -0,0 +1,13 @@
+# `nu-git-manager-sugar git gm repo branch interactive-delete`
+## Description
+remove a branch interactively
+
+
+
+## Parameters
+
+
+## Signatures
+| input | output |
+| ----- | ------ |
+| `any` | `any`  |

docs/nu-git-manager-sugar/git/gm-repo-branch-wipe.md

@@ -0,0 +1,23 @@
+# `nu-git-manager-sugar git gm repo branch wipe`
+## Description
+wipe a branch completely, i.e. both locally and remotely
+
+
+
+## Parameters
+- parameter_name: branch
+- parameter_type: positional
+- syntax_shape: string
+- is_optional: false
+- description: the branch to wipe
+---
+- parameter_name: remote
+- parameter_type: positional
+- syntax_shape: string
+- is_optional: false
+- description: the remote to push to
+
+## Signatures
+| input | output |
+| ----- | ------ |
+| `any` | `any`  |

docs/nu-git-manager-sugar/git/gm-repo-branches.md

@@ -0,0 +1,25 @@
+# `nu-git-manager-sugar git gm repo branches`
+## Description
+inspect local branches
+
+> **Note**  
+> in the following, a "*dangling*" branch refers to a branch that does not have any remote
+> counterpart, i.e. it's a purely local branch.
+
+# Examples
+    list branches and their associated remotes
+    > gm repo branches
+
+    clean all dangling branches
+    > gm repo branches --clean
+
+## Parameters
+- parameter_name: clean
+- parameter_type: switch
+- is_optional: true
+- description: clean all dangling branches
+
+## Signatures
+| input     | output                                         |
+| --------- | ---------------------------------------------- |
+| `nothing` | `table<branch: string, remotes: list<string>>` |

docs/nu-git-manager-sugar/git/gm-repo-compare.md

@@ -0,0 +1,24 @@
+# `nu-git-manager-sugar git gm repo compare`
+## Description
+compare the changes between two revisions, from a target to the "head"
+
+
+
+## Parameters
+- parameter_name: target
+- parameter_type: positional
+- syntax_shape: string
+- is_optional: false
+- description: the target to compare from
+---
+- parameter_name: head
+- parameter_type: named
+- syntax_shape: string
+- is_optional: true
+- description: the "head" to use for the comparison
+- parameter_default: HEAD
+
+## Signatures
+| input | output |
+| ----- | ------ |
+| `any` | `any`  |

docs/nu-git-manager-sugar/git/gm-repo-fetch-branch.md

@@ -0,0 +1,30 @@
+# `nu-git-manager-sugar git gm repo fetch branch`
+## Description
+fetch a remote branch locally, without pulling down the whole remote
+
+
+
+## Parameters
+- parameter_name: remote
+- parameter_type: positional
+- syntax_shape: string
+- is_optional: false
+- description: the branch to fetch
+---
+- parameter_name: branch
+- parameter_type: positional
+- syntax_shape: string
+- is_optional: false
+- description: the remote to fetch the branch from
+---
+- parameter_name: strategy
+- parameter_type: named
+- syntax_shape: string
+- is_optional: true
+- description: the merge strategy to use
+- parameter_default: none
+
+## Signatures
+| input | output |
+| ----- | ------ |
+| `any` | `any`  |

docs/nu-git-manager-sugar/git/gm-repo-get-commit.md

@@ -0,0 +1,23 @@
+# `nu-git-manager-sugar git gm repo get commit`
+## Description
+get the commit hash of any revision
+
+# Examples
+    get the commit hash of the currently checked out revision
+    > gm repo get commit
+
+    get the commit hash of the main branch
+    > gm repo get commit main
+
+## Parameters
+- parameter_name: revision
+- parameter_type: positional
+- syntax_shape: string
+- is_optional: true
+- description: the revision to get the hash of
+- parameter_default: HEAD
+
+## Signatures
+| input     | output   |
+| --------- | -------- |
+| `nothing` | `string` |

docs/nu-git-manager-sugar/git/gm-repo-goto-root.md

@@ -0,0 +1,16 @@
+# `nu-git-manager-sugar git gm repo goto root`
+## Description
+go to the root of the repository from anywhere in the worktree
+
+# Examples
+    go back to the root of a repo
+    > cd foo/bar/baz; gm repo goto root; print (pwd)
+    /path/to/repo
+
+## Parameters
+
+
+## Signatures
+| input     | output    |
+| --------- | --------- |
+| `nothing` | `nothing` |

docs/nu-git-manager-sugar/git/gm-repo-is-ancestor.md

@@ -0,0 +1,30 @@
+# `nu-git-manager-sugar git gm repo is-ancestor`
+## Description
+return true iif the first revision is an ancestor of the second
+
+# Examples
+    HEAD~20 is an ancestor of HEAD
+    > gm repo is-ancestor HEAD~20 HEAD
+    true
+
+    HEAD is never an ancestor of HEAD~20
+    > gm repo is-ancestor HEAD HEAD~20
+    false
+
+## Parameters
+- parameter_name: a
+- parameter_type: positional
+- syntax_shape: string
+- is_optional: false
+- description: the base commit-ish revision
+---
+- parameter_name: b
+- parameter_type: positional
+- syntax_shape: string
+- is_optional: false
+- description: the *head* commit-ish revision
+
+## Signatures
+| input     | output |
+| --------- | ------ |
+| `nothing` | `bool` |

docs/nu-git-manager-sugar/git/gm-repo-ls.md

@@ -0,0 +1,17 @@
+# `nu-git-manager-sugar git gm repo ls`
+## Description
+get some information about a repo
+
+
+
+## Parameters
+- parameter_name: repo
+- parameter_type: positional
+- syntax_shape: path
+- is_optional: true
+- description: the path to the repo (defaults to `.`)
+
+## Signatures
+| input     | output                                                                                                                                                             |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `nothing` | `record<path: string, name: string, staged: int, unstaged: int, untracked: int, last_commit: record<date: datetime, title: string, hash: string>, branch: string>` |

docs/nu-git-manager-sugar/git/gm-repo-remote-list.md

@@ -0,0 +1,19 @@
+# `nu-git-manager-sugar git gm repo remote list`
+## Description
+get the list of all the remotes in the current repository
+# Examples
+    list all the remotes in a default `nu-git-manager` repo
+    > gm repo remote list
+    #┬remote┬──────────────────fetch──────────────────┬─────────────────push──────────────────
+    0│origin│https://github.com/amtoine/nu-git-manager│ssh://github.com/amtoine/nu-git-manager
+    ─┴──────┴─────────────────────────────────────────┴───────────────────────────────────────
+
+
+
+## Parameters
+
+
+## Signatures
+| input     | output                                               |
+| --------- | ---------------------------------------------------- |
+| `nothing` | `table<remote: string, fetch: string, push: string>` |

docs/nu-git-manager-sugar/git/gm-repo-switch.md

@@ -0,0 +1,13 @@
+# `nu-git-manager-sugar git gm repo switch`
+## Description
+switch between branches interactively
+
+
+
+## Parameters
+
+
+## Signatures
+| input     | output    |
+| --------- | --------- |
+| `nothing` | `nothing` |

docs/nu-git-manager-sugar/git/index.md

@@ -0,0 +1,19 @@
+# Module `nu-git-manager-sugar git`
+## Description
+
+
+## Commands
+- [`gm repo branch interactive-delete`](gm-repo-branch-interactive-delete.md)
+- [`gm repo branch wipe`](gm-repo-branch-wipe.md)
+- [`gm repo branches`](gm-repo-branches.md)
+- [`gm repo compare`](gm-repo-compare.md)
+- [`gm repo fetch branch`](gm-repo-fetch-branch.md)
+- [`gm repo get commit`](gm-repo-get-commit.md)
+- [`gm repo goto root`](gm-repo-goto-root.md)
+- [`gm repo is-ancestor`](gm-repo-is-ancestor.md)
+- [`gm repo ls`](gm-repo-ls.md)
+- [`gm repo remote list`](gm-repo-remote-list.md)
+- [`gm repo switch`](gm-repo-switch.md)
+
+## Submodules
+- [`prompt`](prompt/index.md)