From 1a9c0d98920f24baea4f6a5b5d2081c1d91a83e8 Mon Sep 17 00:00:00 2001
From: Antoine Stevan <44101798+amtoine@users.noreply.github.com>
Date: Wed, 13 Dec 2023 16:57:39 +0100
Subject: [PATCH] generate and check documentation (#128)

should
- close #124

## description
as can be seen with
https://github.com/amtoine/nu-git-manager/pull/128/commits/ab1f51505a6b94836ce361575b3fd5806a2f324a,
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     |  34 ++++
 README.md                                     |  27 +--
 docs/index.md                                 |  30 +++
 docs/nu-git-manager-sugar/extra/gm-report.md  |  13 ++
 docs/nu-git-manager-sugar/extra/index.md      |   6 +
 .../git/gm-repo-branch-interactive-delete.md  |  13 ++
 .../git/gm-repo-branch-wipe.md                |  23 +++
 .../git/gm-repo-branches.md                   |  25 +++
 .../git/gm-repo-compare.md                    |  24 +++
 .../git/gm-repo-fetch-branch.md               |  30 +++
 .../git/gm-repo-get-commit.md                 |  23 +++
 .../git/gm-repo-goto-root.md                  |  16 ++
 .../git/gm-repo-is-ancestor.md                |  30 +++
 docs/nu-git-manager-sugar/git/gm-repo-ls.md   |  17 ++
 .../git/gm-repo-remote-list.md                |  19 ++
 .../git/gm-repo-switch.md                     |  13 ++
 docs/nu-git-manager-sugar/git/index.md        |  19 ++
 docs/nu-git-manager-sugar/git/prompt/index.md |   6 +
 docs/nu-git-manager-sugar/git/prompt/setup.md |  47 +++++
 .../github/gm-gh-pr-checkout.md               |  13 ++
 .../github/gm-gh-query-api.md                 |  48 +++++
 .../github/gm-gh-query-releases.md            |  35 ++++
 .../github/gm-gh-query-user.md                |  24 +++
 docs/nu-git-manager-sugar/github/index.md     |   9 +
 docs/nu-git-manager-sugar/index.md            |  11 ++
 docs/nu-git-manager/gm-clean.md               |  25 +++
 docs/nu-git-manager/gm-clone.md               |  70 +++++++
 docs/nu-git-manager/gm-list.md                |  26 +++
 docs/nu-git-manager/gm-remove.md              |  38 ++++
 docs/nu-git-manager/gm-squash-forks.md        |  41 ++++
 docs/nu-git-manager/gm-status.md              |  47 +++++
 docs/nu-git-manager/gm-update-cache.md        |  15 ++
 docs/nu-git-manager/gm.md                     |  34 ++++
 docs/nu-git-manager/index.md                  |  13 ++
 toolkit.nu                                    | 185 +++++++++++++++++-
 35 files changed, 1021 insertions(+), 28 deletions(-)
 create mode 100644 .github/workflows/check-documentation.yml
 create mode 100644 docs/index.md
 create mode 100644 docs/nu-git-manager-sugar/extra/gm-report.md
 create mode 100644 docs/nu-git-manager-sugar/extra/index.md
 create mode 100644 docs/nu-git-manager-sugar/git/gm-repo-branch-interactive-delete.md
 create mode 100644 docs/nu-git-manager-sugar/git/gm-repo-branch-wipe.md
 create mode 100644 docs/nu-git-manager-sugar/git/gm-repo-branches.md
 create mode 100644 docs/nu-git-manager-sugar/git/gm-repo-compare.md
 create mode 100644 docs/nu-git-manager-sugar/git/gm-repo-fetch-branch.md
 create mode 100644 docs/nu-git-manager-sugar/git/gm-repo-get-commit.md
 create mode 100644 docs/nu-git-manager-sugar/git/gm-repo-goto-root.md
 create mode 100644 docs/nu-git-manager-sugar/git/gm-repo-is-ancestor.md
 create mode 100644 docs/nu-git-manager-sugar/git/gm-repo-ls.md
 create mode 100644 docs/nu-git-manager-sugar/git/gm-repo-remote-list.md
 create mode 100644 docs/nu-git-manager-sugar/git/gm-repo-switch.md
 create mode 100644 docs/nu-git-manager-sugar/git/index.md
 create mode 100644 docs/nu-git-manager-sugar/git/prompt/index.md
 create mode 100644 docs/nu-git-manager-sugar/git/prompt/setup.md
 create mode 100644 docs/nu-git-manager-sugar/github/gm-gh-pr-checkout.md
 create mode 100644 docs/nu-git-manager-sugar/github/gm-gh-query-api.md
 create mode 100644 docs/nu-git-manager-sugar/github/gm-gh-query-releases.md
 create mode 100644 docs/nu-git-manager-sugar/github/gm-gh-query-user.md
 create mode 100644 docs/nu-git-manager-sugar/github/index.md
 create mode 100644 docs/nu-git-manager-sugar/index.md
 create mode 100644 docs/nu-git-manager/gm-clean.md
 create mode 100644 docs/nu-git-manager/gm-clone.md
 create mode 100644 docs/nu-git-manager/gm-list.md
 create mode 100644 docs/nu-git-manager/gm-remove.md
 create mode 100644 docs/nu-git-manager/gm-squash-forks.md
 create mode 100644 docs/nu-git-manager/gm-status.md
 create mode 100644 docs/nu-git-manager/gm-update-cache.md
 create mode 100644 docs/nu-git-manager/gm.md
 create mode 100644 docs/nu-git-manager/index.md

diff --git a/.github/workflows/check-documentation.yml b/.github/workflows/check-documentation.yml
new file mode 100644
index 00000000..f24b7de2
--- /dev/null
+++ b/.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/setup-nu@v3.7
+        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\)'
+              }
+            }
+          "
diff --git a/README.md b/README.md
index f1688cfb..0405f889 100644
--- a/README.md
+++ b/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:
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 00000000..9e44ac0d
--- /dev/null
+++ b/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)
diff --git a/docs/nu-git-manager-sugar/extra/gm-report.md b/docs/nu-git-manager-sugar/extra/gm-report.md
new file mode 100644
index 00000000..9ebb0334
--- /dev/null
+++ b/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>` |
diff --git a/docs/nu-git-manager-sugar/extra/index.md b/docs/nu-git-manager-sugar/extra/index.md
new file mode 100644
index 00000000..e1ea6e47
--- /dev/null
+++ b/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)
\ No newline at end of file
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-branch-interactive-delete.md b/docs/nu-git-manager-sugar/git/gm-repo-branch-interactive-delete.md
new file mode 100644
index 00000000..f4e0c8c5
--- /dev/null
+++ b/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`  |
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-branch-wipe.md b/docs/nu-git-manager-sugar/git/gm-repo-branch-wipe.md
new file mode 100644
index 00000000..1234e38f
--- /dev/null
+++ b/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`  |
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-branches.md b/docs/nu-git-manager-sugar/git/gm-repo-branches.md
new file mode 100644
index 00000000..8f45d669
--- /dev/null
+++ b/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>>` |
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-compare.md b/docs/nu-git-manager-sugar/git/gm-repo-compare.md
new file mode 100644
index 00000000..4579981e
--- /dev/null
+++ b/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`  |
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-fetch-branch.md b/docs/nu-git-manager-sugar/git/gm-repo-fetch-branch.md
new file mode 100644
index 00000000..f201e006
--- /dev/null
+++ b/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`  |
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-get-commit.md b/docs/nu-git-manager-sugar/git/gm-repo-get-commit.md
new file mode 100644
index 00000000..69cb0426
--- /dev/null
+++ b/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` |
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-goto-root.md b/docs/nu-git-manager-sugar/git/gm-repo-goto-root.md
new file mode 100644
index 00000000..6b58323e
--- /dev/null
+++ b/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` |
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-is-ancestor.md b/docs/nu-git-manager-sugar/git/gm-repo-is-ancestor.md
new file mode 100644
index 00000000..81c62a1b
--- /dev/null
+++ b/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` |
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-ls.md b/docs/nu-git-manager-sugar/git/gm-repo-ls.md
new file mode 100644
index 00000000..1b69a504
--- /dev/null
+++ b/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>` |
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-remote-list.md b/docs/nu-git-manager-sugar/git/gm-repo-remote-list.md
new file mode 100644
index 00000000..392d15da
--- /dev/null
+++ b/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>` |
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-switch.md b/docs/nu-git-manager-sugar/git/gm-repo-switch.md
new file mode 100644
index 00000000..1c05af50
--- /dev/null
+++ b/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` |
diff --git a/docs/nu-git-manager-sugar/git/index.md b/docs/nu-git-manager-sugar/git/index.md
new file mode 100644
index 00000000..dcba42e3
--- /dev/null
+++ b/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)
\ No newline at end of file
diff --git a/docs/nu-git-manager-sugar/git/prompt/index.md b/docs/nu-git-manager-sugar/git/prompt/index.md
new file mode 100644
index 00000000..b96f0873
--- /dev/null
+++ b/docs/nu-git-manager-sugar/git/prompt/index.md
@@ -0,0 +1,6 @@
+# Module `nu-git-manager-sugar git prompt`
+## Description
+
+
+## Commands
+- [`setup`](setup.md)
\ No newline at end of file
diff --git a/docs/nu-git-manager-sugar/git/prompt/setup.md b/docs/nu-git-manager-sugar/git/prompt/setup.md
new file mode 100644
index 00000000..29035074
--- /dev/null
+++ b/docs/nu-git-manager-sugar/git/prompt/setup.md
@@ -0,0 +1,47 @@
+# `nu-git-manager-sugar git prompt setup`
+## Description
+setup the Git prompt of NGM
+
+the different sections of the prompt are the following, in order and separated by a single space:
+- "admin_segment": shows if you are an admin of the session
+- "pwd": shows the current working directory, in long form outside of a repo or with only the
+    basename if inside a Git repo
+- "git_branch_segment": if inside a Git repo, will show the current branch, the tag or the
+    detached revision
+- "git_action_segment": if inside a Git repo and performing a Git action, such as a MERGE or a
+    REBASE, the prompt will show the stage of the action
+- "duration_segment": if the last command took longer than the `--duration-threshold`, the prompt
+    will show the exact duration
+- "command_failed_segment": if the last command failed, the exit code will be shown
+- "login_segment": shows if you are in a login session
+
+# Examples
+    setup the prompt with 10sec of command duration and `> ` as the Vi indicator
+    > export-env {
+          use nu-git-manager-sugar git-prompt setup
+          setup --duration-threshold 10sec --indicators {
+              vi: {
+                  insert: "> "
+                  normal: "> "
+              }
+          }
+      }
+
+## Parameters
+- parameter_name: indicators
+- parameter_type: named
+- syntax_shape: record<plain: string, vi: record<insert: string, normal: string>>
+- is_optional: true
+- parameter_default: plain: > , vi: insert: : , normal: > 
+---
+- parameter_name: duration-threshold
+- parameter_type: named
+- syntax_shape: duration
+- is_optional: true
+- description: the threshold above which the command duration is shown
+- parameter_default: 1sec
+
+## Signatures
+| input | output |
+| ----- | ------ |
+| `any` | `any`  |
diff --git a/docs/nu-git-manager-sugar/github/gm-gh-pr-checkout.md b/docs/nu-git-manager-sugar/github/gm-gh-pr-checkout.md
new file mode 100644
index 00000000..c8fc778b
--- /dev/null
+++ b/docs/nu-git-manager-sugar/github/gm-gh-pr-checkout.md
@@ -0,0 +1,13 @@
+# `nu-git-manager-sugar github gm gh pr checkout`
+## Description
+checkout one of the repo's PR interactively
+
+
+
+## Parameters
+
+
+## Signatures
+| input | output |
+| ----- | ------ |
+| `any` | `any`  |
diff --git a/docs/nu-git-manager-sugar/github/gm-gh-query-api.md b/docs/nu-git-manager-sugar/github/gm-gh-query-api.md
new file mode 100644
index 00000000..0c7c1b80
--- /dev/null
+++ b/docs/nu-git-manager-sugar/github/gm-gh-query-api.md
@@ -0,0 +1,48 @@
+# `nu-git-manager-sugar github gm gh query-api`
+## Description
+query the GitHub API for any end point
+
+> :bulb: **Note**  
+> see the [rest API of GitHub](https://docs.github.com/en/rest) for a complete
+> list of available end points and documentation
+
+# Examples
+    list the releases of Nushell sorted by date
+    > gm gh query-api "/repos/nushell/nushell/releases"
+          | select tag_name published_at
+          | rename tag date
+          | into datetime date
+          | sort-by date
+
+    get the bio of @amtoine
+    > gm gh query-api --no-paginate "/users/amtoine" | get bio
+    you shall not rebase in the middle of a PR review nor close other's review threads :pray:
+
+## Parameters
+- parameter_name: end_point
+- parameter_type: positional
+- syntax_shape: string
+- is_optional: false
+- description: the end point in the GitHub API to query
+---
+- parameter_name: page-size
+- parameter_type: named
+- syntax_shape: int
+- is_optional: true
+- description: the size of each page
+- parameter_default: 100
+---
+- parameter_name: no-paginate
+- parameter_type: switch
+- is_optional: true
+- description: do not paginate the API, useful when getting a single record
+---
+- parameter_name: no-gh
+- parameter_type: switch
+- is_optional: true
+- description: force to use `http get` instead of `gh`
+
+## Signatures
+| input     | output |
+| --------- | ------ |
+| `nothing` | `any`  |
diff --git a/docs/nu-git-manager-sugar/github/gm-gh-query-releases.md b/docs/nu-git-manager-sugar/github/gm-gh-query-releases.md
new file mode 100644
index 00000000..8f4d0b41
--- /dev/null
+++ b/docs/nu-git-manager-sugar/github/gm-gh-query-releases.md
@@ -0,0 +1,35 @@
+# `nu-git-manager-sugar github gm gh query-releases`
+## Description
+list the releases of a GitHub repository
+
+# Examples
+    get the last release of the `github.com:nushell/nushell` repository
+    > gm gh query-releases "nushell/nushell"
+          | into datetime published_at
+          | sort-by published_at
+          | last
+          | select tag_name published_at
+
+## Parameters
+- parameter_name: repo
+- parameter_type: positional
+- syntax_shape: string
+- is_optional: false
+- description: the GitHub repository to query the releases of
+---
+- parameter_name: page-size
+- parameter_type: named
+- syntax_shape: int
+- is_optional: true
+- description: the size of each page
+- parameter_default: 100
+---
+- parameter_name: no-gh
+- parameter_type: switch
+- is_optional: true
+- description: force to use `http get` instead of `gh`
+
+## Signatures
+| input     | output                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `nothing` | `table<url: string, assets_url: string, upload_url: string, html_url: string, id: int, author: record<login: string, id: int, node_id: string, avatar_url: string, gravatar_id: string, url: string, html_url: string, followers_url: string, following_url: string, gists_url: string, starred_url: string, subscriptions_url: string, organizations_url: string, repos_url: string, events_url: string, received_events_url: string, type: string, site_admin: bool>, node_id: string, tag_name: string, target_commitish: string, name: string, draft: bool, prerelease: bool, created_at: string, published_at: string, assets: list<any>, tarball_url: string, zipball_url: string, body: string, reactions: record<url: string, total_count: int, +1: int, -1: int, laugh: int, hooray: int, confused: int, heart: int, rocket: int, eyes: int>, mentions_count: int>` |
diff --git a/docs/nu-git-manager-sugar/github/gm-gh-query-user.md b/docs/nu-git-manager-sugar/github/gm-gh-query-user.md
new file mode 100644
index 00000000..b587c74c
--- /dev/null
+++ b/docs/nu-git-manager-sugar/github/gm-gh-query-user.md
@@ -0,0 +1,24 @@
+# `nu-git-manager-sugar github gm gh query-user`
+## Description
+get information about a GitHub user
+
+Examples:
+    get the avatar picture of @amtoine
+    > gm gh query-user amtoine | get avatar_url | http get $in | save --force amtoine.png
+
+## Parameters
+- parameter_name: user
+- parameter_type: positional
+- syntax_shape: string
+- is_optional: false
+- description: the user to query information about
+---
+- parameter_name: no-gh
+- parameter_type: switch
+- is_optional: true
+- description: force to use `http get` instead of `gh`
+
+## Signatures
+| input     | output                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `nothing` | `record<login: string, id: int, node_id: string, avatar_url: string, gravatar_id: string, url: string, html_url: string, followers_url: string, following_url: string, gists_url: string, starred_url: string, subscriptions_url: string, organizations_url: string, repos_url: string, events_url: string, received_events_url: string, type: string, site_admin: bool, name: string, company: string, blog: string, location: string, email: nothing, hireable: nothing, bio: string, twitter_username: nothing, public_repos: int, public_gists: int, followers: int, following: int, created_at: string, updated_at: string>` |
diff --git a/docs/nu-git-manager-sugar/github/index.md b/docs/nu-git-manager-sugar/github/index.md
new file mode 100644
index 00000000..f713725d
--- /dev/null
+++ b/docs/nu-git-manager-sugar/github/index.md
@@ -0,0 +1,9 @@
+# Module `nu-git-manager-sugar github`
+## Description
+
+
+## Commands
+- [`gm gh pr checkout`](gm-gh-pr-checkout.md)
+- [`gm gh query-api`](gm-gh-query-api.md)
+- [`gm gh query-releases`](gm-gh-query-releases.md)
+- [`gm gh query-user`](gm-gh-query-user.md)
\ No newline at end of file
diff --git a/docs/nu-git-manager-sugar/index.md b/docs/nu-git-manager-sugar/index.md
new file mode 100644
index 00000000..fdb766ef
--- /dev/null
+++ b/docs/nu-git-manager-sugar/index.md
@@ -0,0 +1,11 @@
+# Module `nu-git-manager-sugar`
+## Description
+
+
+## Commands
+no commands
+
+## Submodules
+- [`extra`](extra/index.md)
+- [`git`](git/index.md)
+- [`github`](github/index.md)
\ No newline at end of file
diff --git a/docs/nu-git-manager/gm-clean.md b/docs/nu-git-manager/gm-clean.md
new file mode 100644
index 00000000..3154398f
--- /dev/null
+++ b/docs/nu-git-manager/gm-clean.md
@@ -0,0 +1,25 @@
+# `nu-git-manager gm clean`
+## Description
+clean the store
+
+this command will mainly remove empty directory recursively.
+
+/!\ this command will return sanitized paths. /!\
+
+Examples
+    clean the store
+    > gm clean
+
+    list the leaves of the store that would have to be cleaned
+    > gm clean --list
+
+## Parameters
+- parameter_name: list
+- parameter_type: switch
+- is_optional: true
+- description: only list without cleaning
+
+## Signatures
+| input     | output         |
+| --------- | -------------- |
+| `nothing` | `list<string>` |
diff --git a/docs/nu-git-manager/gm-clone.md b/docs/nu-git-manager/gm-clone.md
new file mode 100644
index 00000000..8703e552
--- /dev/null
+++ b/docs/nu-git-manager/gm-clone.md
@@ -0,0 +1,70 @@
+# `nu-git-manager gm clone`
+## Description
+clone a remote Git repository into your local store
+
+will give a nice error if the repository is already in the local store.
+
+# Examples
+    clone a repository in the local store of `nu-git-manager`
+    > gm clone https://github.com/amtoine/nu-git-manager
+
+    clone as a bare repository, i.e. a repo without a worktree
+    > gm clone --bare https://github.com/amtoine/nu-git-manager
+
+    clone a repo and change the name of the remote
+    > gm clone --remote default https://github.com/amtoine/nu-git-manager
+
+    setup a public repo in the local store and use HTTP to fetch without PAT and push with SSH
+    > gm clone https://github.com/amtoine/nu-git-manager --fetch https --push ssh
+
+    clone a big repo as a single commit, avoiding all intermediate Git deltas
+    > gm clone https://github.com/neovim/neovim --depth 1
+
+## Parameters
+- parameter_name: url
+- parameter_type: positional
+- syntax_shape: string
+- is_optional: false
+- description: the URL to the repository to clone, supports HTTPS and SSH links, as well as references ending in `.git` or starting with `git@`
+---
+- parameter_name: remote
+- parameter_type: named
+- syntax_shape: string
+- is_optional: true
+- description: the name of the remote to setup
+- parameter_default: origin
+---
+- parameter_name: ssh
+- parameter_type: switch
+- is_optional: true
+- description: setup the remote to use the SSH protocol both to FETCH and to PUSH
+---
+- parameter_name: fetch
+- parameter_type: named
+- syntax_shape: completable<string>
+- is_optional: true
+- description: setup the FETCH protocol explicitely, will overwrite `--ssh` for FETCH
+- custom_completion: git-protocols
+---
+- parameter_name: push
+- parameter_type: named
+- syntax_shape: completable<string>
+- is_optional: true
+- description: setup the PUSH protocol explicitely, will overwrite `--ssh` for PUSH
+- custom_completion: git-protocols
+---
+- parameter_name: bare
+- parameter_type: switch
+- is_optional: true
+- description: clone the repository as a "bare" project
+---
+- parameter_name: depth
+- parameter_type: named
+- syntax_shape: int
+- is_optional: true
+- description: the depth at which to clone the repository
+
+## Signatures
+| input     | output    |
+| --------- | --------- |
+| `nothing` | `nothing` |
diff --git a/docs/nu-git-manager/gm-list.md b/docs/nu-git-manager/gm-list.md
new file mode 100644
index 00000000..532fb08a
--- /dev/null
+++ b/docs/nu-git-manager/gm-list.md
@@ -0,0 +1,26 @@
+# `nu-git-manager gm list`
+## Description
+list all the local repositories in your local store
+
+/!\ this command will return sanitized paths. /!\
+
+# Examples
+    list all the repositories in the store
+    > gm list
+
+    list all the repositories in the store with their full paths
+    > gm list --full-path
+
+    jump to a directory in the store
+    > cd (gm list --full-path | input list)
+
+## Parameters
+- parameter_name: full-path
+- parameter_type: switch
+- is_optional: true
+- description: show the full path instead of only the "owner + group + repo" name
+
+## Signatures
+| input     | output         |
+| --------- | -------------- |
+| `nothing` | `list<string>` |
diff --git a/docs/nu-git-manager/gm-remove.md b/docs/nu-git-manager/gm-remove.md
new file mode 100644
index 00000000..4735b817
--- /dev/null
+++ b/docs/nu-git-manager/gm-remove.md
@@ -0,0 +1,38 @@
+# `nu-git-manager gm remove`
+## Description
+remove one of the repositories from your local store
+
+# Examples
+    remove any repository by fuzzy-finding the whole store
+    > gm remove --fuzzy
+
+    restrict the search to any one of my repositories
+    > gm remove amtoine
+
+    remove a precise repo by giving its full name, a name collision is unlikely
+    > gm remove amtoine/nu-git-manager
+
+    remove a precise repo without confirmation
+    > gm remove amtoine/nu-git-manager --no-confirm
+
+## Parameters
+- parameter_name: pattern
+- parameter_type: positional
+- syntax_shape: string
+- is_optional: true
+- description: a pattern to restrict the choices
+---
+- parameter_name: fuzzy
+- parameter_type: switch
+- is_optional: true
+- description: remove after fuzzy-finding the repo(s) to clean
+---
+- parameter_name: no-confirm
+- parameter_type: switch
+- is_optional: true
+- description: do not ask for confirmation: useful in scripts but requires a single match
+
+## Signatures
+| input     | output    |
+| --------- | --------- |
+| `nothing` | `nothing` |
diff --git a/docs/nu-git-manager/gm-squash-forks.md b/docs/nu-git-manager/gm-squash-forks.md
new file mode 100644
index 00000000..66a5cedd
--- /dev/null
+++ b/docs/nu-git-manager/gm-squash-forks.md
@@ -0,0 +1,41 @@
+# `nu-git-manager gm squash-forks`
+## Description
+squash multi-directory forks into a single repo
+
+Here, two forks are defined as *two non-grafted repositories that share the same initial commit,
+i.e. that have the same root hash in their respective DAGs*.
+
+By default, `gm squash-forks` will prompt the user for a main fork for each repository with
+multiple forks.
+Once a *main* fork has been chosen, for each one of the other secondary forks, the command will
+preform the following steps:
+- add the secondary fork as a remote to the main one
+- setup the FETCH and PUSH remotes to the same ones as the secondary fork in the main one
+- remove the secondary fork entirely from the store and the cache
+
+This operation can be done in a non-interactive manner by specifying `--non-interactive-preselect`.
+This option is a `record` with
+- keys: the root hash of repos, e.g. [2ed2d87](https://github.com/amtoine/nu-git-manager/commit/2ed2d875d80505d78423328c6b2a60522715fcdf) for `nu-git-manager`
+- values: the main fork to select in full-name form, e.g. `github.com/amtoine/nu-git-manager`
+
+# Examples
+    squash forks interactively
+    > gm squash-forks
+
+    squash forks non-interactively: `nu-git-manager` and `nushell` to the forks of @amtoine
+    > gm squash-forks --non-interactive-preselect {
+          2ed2d875d80505d78423328c6b2a60522715fcdf: "github.com/amtoine/nu-git-manager",
+          8f3b273337b53bd86d5594d5edc9d4ad7242bd4c: "github.com/amtoine/nushell",
+      }
+
+## Parameters
+- parameter_name: non-interactive-preselect
+- parameter_type: named
+- syntax_shape: record
+- is_optional: true
+- description: the non-interactive preselection record, see documentation above
+
+## Signatures
+| input     | output    |
+| --------- | --------- |
+| `nothing` | `nothing` |
diff --git a/docs/nu-git-manager/gm-status.md b/docs/nu-git-manager/gm-status.md
new file mode 100644
index 00000000..38d34f07
--- /dev/null
+++ b/docs/nu-git-manager/gm-status.md
@@ -0,0 +1,47 @@
+# `nu-git-manager gm status`
+## Description
+get current status about the repositories managed by `nu-git-manager`
+
+/!\ `$.root.path` and `$.cache.path` will be sanitized /!\
+
+Examples
+    getting status when everything is fine
+    > gm status | reject missing | flatten | into record
+    ╭─────────────────────┬────────────────────────────────────╮
+    │ path                │ ~/.local/share/repos               │
+    │ exists              │ true                               │
+    │ cache_path          │ ~/.cache/nu-git-manager/cache.nuon │
+    │ cache_exists        │ true                               │
+    │ should_update_cache │ false                              │
+    ╰─────────────────────┴────────────────────────────────────╯
+
+    getting status when there is no store
+    > gm status | get root
+    ╭────────┬──────────────────────╮
+    │ path   │ ~/.local/share/repos │
+    │ exists │ false                │
+    ╰────────┴──────────────────────╯
+
+    getting status when there is no cache
+    > gm status | get root
+    ╭────────┬────────────────────────────────────╮
+    │ path   │ ~/.cache/nu-git-manager/cache.nuon │
+    │ exists │ false                              │
+    ╰────────┴────────────────────────────────────╯
+
+    getting status when a project is in the cache but is missing on the filesystem
+    > gm status | get missing
+    ╭──────────────────────────────────────╮
+    │ 0 │ ~/.local/share/repos/foo/bar/baz │
+    ╰──────────────────────────────────────╯
+
+    update the cache if necessary
+    > if (gm status).should_update_cache { gm update-cache }
+
+## Parameters
+
+
+## Signatures
+| input     | output                                                                                                                                          |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `nothing` | `record<root: record<path: string, exists: bool>, missing: list<string>, cache: record<path: string, exists: bool>, should_update_cache: bool>` |
diff --git a/docs/nu-git-manager/gm-update-cache.md b/docs/nu-git-manager/gm-update-cache.md
new file mode 100644
index 00000000..f93ae396
--- /dev/null
+++ b/docs/nu-git-manager/gm-update-cache.md
@@ -0,0 +1,15 @@
+# `nu-git-manager gm update-cache`
+## Description
+update the local cache of repositories
+
+# Examples
+    update the cache of repositories
+    > gm update-cache
+
+## Parameters
+
+
+## Signatures
+| input     | output    |
+| --------- | --------- |
+| `nothing` | `nothing` |
diff --git a/docs/nu-git-manager/gm.md b/docs/nu-git-manager/gm.md
new file mode 100644
index 00000000..462429e3
--- /dev/null
+++ b/docs/nu-git-manager/gm.md
@@ -0,0 +1,34 @@
+# `nu-git-manager gm`
+## Description
+manage your Git repositories with the main command of `nu-git-manager`
+
+`nu-git-manager` will look for a store in the following places, in order:
+- `$env.GIT_REPOS_HOME`
+- `$env.XDG_DATA_HOME | path join "repos"
+- `~/.local/share/repos`
+
+`nu-git-manager` will look for a cache in the following places, in order:
+- `$env.GIT_REPOS_CACHE`
+- `$env.XDG_CACHE_HOME | path join "nu-git-manager/cache.nuon"
+- `~/.cache/nu-git-manager/cache.nuon`
+
+# Examples
+    a contrived example to set the path to the root of the store
+    > with-env { GIT_REPOS_HOME: ($nu.home-path | path join "foo") } {
+          gm status | get root.path | str replace $nu.home-path '~'
+      }
+    ~/foo
+
+    a contrived example to set the path to the cache of the store
+    > with-env { XDG_CACHE_HOME: ($nu.home-path | path join "foo") } {
+          gm status | get cache.path | str replace $nu.home-path '~'
+      }
+    ~/foo/nu-git-manager/cache.nuon
+
+## Parameters
+
+
+## Signatures
+| input     | output    |
+| --------- | --------- |
+| `nothing` | `nothing` |
diff --git a/docs/nu-git-manager/index.md b/docs/nu-git-manager/index.md
new file mode 100644
index 00000000..c4507c5a
--- /dev/null
+++ b/docs/nu-git-manager/index.md
@@ -0,0 +1,13 @@
+# Module `nu-git-manager`
+## Description
+
+
+## Commands
+- [`gm`](gm.md)
+- [`gm clean`](gm-clean.md)
+- [`gm clone`](gm-clone.md)
+- [`gm list`](gm-list.md)
+- [`gm remove`](gm-remove.md)
+- [`gm squash-forks`](gm-squash-forks.md)
+- [`gm status`](gm-status.md)
+- [`gm update-cache`](gm-update-cache.md)
\ No newline at end of file
diff --git a/toolkit.nu b/toolkit.nu
index 9f0cec49..6f858581 100644
--- a/toolkit.nu
+++ b/toolkit.nu
@@ -1,3 +1,5 @@
+use std repeat
+
 # run the tests of the `nu-git-manager` package
 #
 # > **Important**  
@@ -6,19 +8,22 @@ export def "test" [
     pattern?: string = "" # the pattern a test name should match to run
     --verbose # show the output of each tests
 ]: nothing -> nothing {
-    use nupm
-
-    if $verbose {
-        nupm test $pattern --show-stdout
+    let command = if $verbose {
+        $"nupm test ($pattern) --show-stdout"
     } else {
-        nupm test $pattern
+        $"nupm test ($pattern)"
     }
+
+    # NOTE: this is for the CI to pass without installing Nupm
+    ^$nu.current-exe --env-config $nu.env-path --commands $"use nupm; ($command)"
 }
 
 # install `nu-git-manager` with Nupm
 export def "install" []: nothing -> nothing {
-    use nupm
-    nupm install --force --path (^git rev-parse --show-toplevel)
+    let command = "nupm install --force --path (^git rev-parse --show-toplevel)"
+
+    # NOTE: this is for the CI to pass without installing Nupm
+    ^$nu.current-exe --env-config $nu.env-path --commands $"use nupm; ($command)"
 }
 
 # run some code inside an isolated environment
@@ -132,3 +137,169 @@ export def get-ignored-tests []: nothing -> table<file: string, test: string, re
             $it.1 | parse "{file}-def {test} [{rest}" | reject rest | insert reason $reason | first
         }
 }
+
+def run-nu [code: string]: nothing -> any {
+    ^$nu.current-exe --no-config-file --commands ($code ++ " | to nuon") | from nuon
+}
+
+def document-command [
+    args: record<module_name: string, full_module_name_with_leading_path: string, root: path>
+]: string -> string {
+    let command = $in
+
+    let command_file = $command
+        | str replace --all ' ' '-'
+        | path parse
+        | update extension md
+        | path join
+
+    let help = run-nu $"
+        use ($args.root)/($args.full_module_name_with_leading_path) '($command)'
+        scope commands | where name == '($command)' | into record
+    "
+
+    let signatures = $help.signatures | transpose | get column1
+
+    let page = [
+        $"# `($args.module_name) ($command)`",
+        $"## Description",
+        $help.usage,
+        "",
+        $help.extra_usage,
+        "",
+        "## Parameters",
+        (
+            $signatures.0
+                | where parameter_type not-in ["input", "output"]
+                | each {
+                    transpose
+                        | where not ($it.column1 | is-empty)
+                        | transpose --header-row
+                        | into record
+                        | to text
+                        | lines
+                        | str replace --regex '^' '- '
+                        | str join "\n"
+                }
+                | str join "\n---\n"
+        ),
+        "",
+        $"## Signatures",
+        (
+            $signatures
+                | each {
+                    where parameter_type in ["input", "output"]
+                        | select parameter_type syntax_shape
+                        | transpose --header-row
+                }
+                | flatten
+                | update input { $"`($in)`" }
+                | update output { $"`($in)`" }
+                | to md --pretty
+        ),
+    ]
+
+    $page | flatten | str join "\n" | save --force --append $command_file
+
+    $command_file
+}
+
+# /!\ will save each command encountered to the main index file as a side effect
+def document-module [
+    module_path: string, --root: path, --documentation-dir: path
+]: nothing -> nothing {
+    let main_index = $root | path join $documentation_dir "index.md"
+
+    def aux [
+        full_module_name_with_leading_path: string,
+        depth?: int = 0,
+    ]: record<name: string, commands: list<string>, submodules: list<record>> -> nothing {
+        let module = $in
+
+        mkdir ($module.name | path basename)
+        cd ($module.name | path basename)
+
+        let module_name = (
+            ($full_module_name_with_leading_path | split row ' ' | get 0 | path basename)
+            + ' '
+            + ($full_module_name_with_leading_path | split row ' ' | skip 1 | str join ' ')
+        )
+            | str trim
+
+        let commands = if ($module.commands.name | is-empty) {
+            "no commands"
+        } else {
+            $module.commands.name | each {|command|
+                let command_file = $command | document-command {
+                    module_name: $module_name,
+                    full_module_name_with_leading_path: $full_module_name_with_leading_path,
+                    root: $root,
+                }
+
+                let full_command_file = (
+                    $module_name | str replace --all ' ' '/' | path join $command_file
+                )
+                $"- [`($command)`]\(($full_command_file)\)\n" | save --force --append $main_index
+
+                $"- [`($command)`]\(($command_file)\)"
+            }
+        }
+
+        let submodules = if ($module.submodules | is-empty) {
+            ""
+        } else {
+            $module.submodules | each {|submodule|
+                $"- [`($submodule.name)`]\(($submodule.name)/index.md\)"
+            }
+        }
+
+        let page = [
+            $"# Module `($module_name)`",
+            "## Description",
+            $module.usage,
+            "",
+            "## Commands",
+            $commands,
+        ]
+        let page = if ($submodules | is-empty) {
+            $page
+        } else {
+            $page | append ["", "## Submodules", $submodules]
+        }
+
+        $page | flatten | str join "\n" | save --force index.md
+
+
+        for submodule in $module.submodules {
+            $submodule | aux ($full_module_name_with_leading_path + ' ' + $submodule.name) ($depth + 1)
+        }
+    }
+
+    let module = run-nu $"
+        use ($root)/($module_path)
+        scope modules | where name == ($module_path | path basename) | into record
+    "
+
+    $module | aux $module_path
+}
+
+export def doc [--documentation-dir: path = "./docs/"] {
+    let modules = open package.nuon | get modules
+
+    let documentation_dir = $documentation_dir | path expand
+
+    rm --force --recursive $documentation_dir
+    mkdir $documentation_dir
+    cd $documentation_dir
+
+    "## Modules\n" | save --force --append index.md
+    for module in ($modules | path basename) {
+        $"- [`($module)`]\(./($module)/index.md\)\n" | save --force --append index.md
+    }
+
+    "\n" | save --force --append index.md
+    "## Commands\n" | save --force --append index.md
+    for module in $modules {
+        document-module $module --root (pwd | path dirname) --documentation-dir $documentation_dir
+    }
+}