From 60f6b860b8aa8fcca9402dbbd78abb977b35f8fd Mon Sep 17 00:00:00 2001
From: Antoine Stevan <44101798+amtoine@users.noreply.github.com>
Date: Thu, 25 Jan 2024 19:44:19 +0100
Subject: [PATCH] link to the source of each command in the doc (#166)

the _real_ changes happen in `toolkit.nu` and around the
`nu-git-manager-sugar git prompt setup` command.
the rest is just regenerating the documentation with `toolkit doc`.
---
 docs/nu-git-manager-sugar/extra/gm-report.md  |  2 +-
 .../git/gm-repo-bisect.md                     |  2 +-
 .../git/gm-repo-branch-interactive-delete.md  |  2 +-
 .../git/gm-repo-branch-wipe.md                |  2 +-
 .../git/gm-repo-branches.md                   |  2 +-
 .../git/gm-repo-compare.md                    |  2 +-
 .../git/gm-repo-fetch-branch.md               |  2 +-
 .../git/gm-repo-get-commit.md                 |  2 +-
 .../git/gm-repo-goto-root.md                  |  2 +-
 .../git/gm-repo-is-ancestor.md                |  2 +-
 docs/nu-git-manager-sugar/git/gm-repo-ls.md   |  2 +-
 .../nu-git-manager-sugar/git/gm-repo-query.md |  2 +-
 .../git/gm-repo-remote-list.md                |  2 +-
 .../git/gm-repo-switch.md                     |  2 +-
 docs/nu-git-manager-sugar/git/prompt/setup.md |  2 +-
 .../github/gm-gh-pr-checkout.md               |  2 +-
 .../github/gm-gh-query-api.md                 |  2 +-
 .../github/gm-gh-query-releases.md            |  2 +-
 .../github/gm-gh-query-user.md                |  2 +-
 docs/nu-git-manager/gm-clean.md               |  2 +-
 docs/nu-git-manager/gm-clone.md               |  2 +-
 docs/nu-git-manager/gm-list.md                |  2 +-
 docs/nu-git-manager/gm-remove.md              |  2 +-
 docs/nu-git-manager/gm-squash-forks.md        |  2 +-
 docs/nu-git-manager/gm-status.md              |  2 +-
 docs/nu-git-manager/gm-update-cache.md        |  2 +-
 docs/nu-git-manager/gm.md                     |  2 +-
 .../nu-git-manager-sugar/git/prompt.nu        |  2 +-
 toolkit.nu                                    | 28 ++++++++++++++++++-
 29 files changed, 55 insertions(+), 29 deletions(-)

diff --git a/docs/nu-git-manager-sugar/extra/gm-report.md b/docs/nu-git-manager-sugar/extra/gm-report.md
index 4a8a095..5b6d8b3 100644
--- a/docs/nu-git-manager-sugar/extra/gm-report.md
+++ b/docs/nu-git-manager-sugar/extra/gm-report.md
@@ -1,4 +1,4 @@
-# `gm report` (`nu-git-manager-sugar extra`)
+# `gm report` from `nu-git-manager-sugar extra` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/extra.nu#L23))
 get a full report about the local store of repositories
 
 ## Examples
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-bisect.md b/docs/nu-git-manager-sugar/git/gm-repo-bisect.md
index f4e561e..43cc174 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-bisect.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-bisect.md
@@ -1,4 +1,4 @@
-# `gm repo bisect` (`nu-git-manager-sugar git`)
+# `gm repo bisect` from `nu-git-manager-sugar git` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/git/mod.nu#L380))
 bisect a worktree by running a piece of code repeatedly
 
 # Examples
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
index e59cb88..7dcf34e 100644
--- 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
@@ -1,4 +1,4 @@
-# `gm repo branch interactive-delete` (`nu-git-manager-sugar git`)
+# `gm repo branch interactive-delete` from `nu-git-manager-sugar git` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/git/mod.nu#L226))
 remove a branch interactively
 
 
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
index 965c179..2905a6f 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-branch-wipe.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-branch-wipe.md
@@ -1,4 +1,4 @@
-# `gm repo branch wipe` (`nu-git-manager-sugar git`)
+# `gm repo branch wipe` from `nu-git-manager-sugar git` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/git/mod.nu#L113))
 wipe a branch completely, i.e. both locally and remotely
 
 
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-branches.md b/docs/nu-git-manager-sugar/git/gm-repo-branches.md
index 5c4f056..c87f1f5 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-branches.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-branches.md
@@ -1,4 +1,4 @@
-# `gm repo branches` (`nu-git-manager-sugar git`)
+# `gm repo branches` from `nu-git-manager-sugar git` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/git/mod.nu#L72))
 inspect local branches
 
 > **Note**  
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-compare.md b/docs/nu-git-manager-sugar/git/gm-repo-compare.md
index 212e41a..a002add 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-compare.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-compare.md
@@ -1,4 +1,4 @@
-# `gm repo compare` (`nu-git-manager-sugar git`)
+# `gm repo compare` from `nu-git-manager-sugar git` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/git/mod.nu#L31))
 compare the changes between two revisions, from a target to the "head"
 
 
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
index 26f2d0e..744a1bd 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-fetch-branch.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-fetch-branch.md
@@ -1,4 +1,4 @@
-# `gm repo fetch branch` (`nu-git-manager-sugar git`)
+# `gm repo fetch branch` from `nu-git-manager-sugar git` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/git/mod.nu#L174))
 fetch a remote branch locally, without pulling down the whole remote
 
 
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
index fa735f7..b8a211c 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-get-commit.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-get-commit.md
@@ -1,4 +1,4 @@
-# `gm repo get commit` (`nu-git-manager-sugar git`)
+# `gm repo get commit` from `nu-git-manager-sugar git` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/git/mod.nu#L24))
 get the commit hash of any revision
 
 ## Examples
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
index 751495c..36da0d8 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-goto-root.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-goto-root.md
@@ -1,4 +1,4 @@
-# `gm repo goto root` (`nu-git-manager-sugar git`)
+# `gm repo goto root` from `nu-git-manager-sugar git` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/git/mod.nu#L52))
 go to the root of the repository from anywhere in the worktree
 
 ## Examples
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
index bbcc93b..2524233 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-is-ancestor.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-is-ancestor.md
@@ -1,4 +1,4 @@
-# `gm repo is-ancestor` (`nu-git-manager-sugar git`)
+# `gm repo is-ancestor` from `nu-git-manager-sugar git` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/git/mod.nu#L140))
 return true iif the first revision is an ancestor of the second
 
 ## Examples
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-ls.md b/docs/nu-git-manager-sugar/git/gm-repo-ls.md
index 7ea01e4..4d8f9dc 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-ls.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-ls.md
@@ -1,4 +1,4 @@
-# `gm repo ls` (`nu-git-manager-sugar git`)
+# `gm repo ls` from `nu-git-manager-sugar git` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/git/mod.nu#L270))
 get some information about a repo
 
 
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-query.md b/docs/nu-git-manager-sugar/git/gm-repo-query.md
index 03fcd2a..148588b 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-query.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-query.md
@@ -1,4 +1,4 @@
-# `gm repo query` (`nu-git-manager-sugar git`)
+# `gm repo query` from `nu-git-manager-sugar git` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/git/mod.nu#L320))
 queries the `.git/` directory as a database with `nu_plugin_git_query`
 
 ## Examples
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
index d704539..a2316e7 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-remote-list.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-remote-list.md
@@ -1,4 +1,4 @@
-# `gm repo remote list` (`nu-git-manager-sugar git`)
+# `gm repo remote list` from `nu-git-manager-sugar git` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/git/mod.nu#L159))
 get the list of all the remotes in the current repository
 
 ## Examples
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-switch.md b/docs/nu-git-manager-sugar/git/gm-repo-switch.md
index e282694..9a487b6 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-switch.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-switch.md
@@ -1,4 +1,4 @@
-# `gm repo switch` (`nu-git-manager-sugar git`)
+# `gm repo switch` from `nu-git-manager-sugar git` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/git/mod.nu#L246))
 switch between branches interactively
 
 
diff --git a/docs/nu-git-manager-sugar/git/prompt/setup.md b/docs/nu-git-manager-sugar/git/prompt/setup.md
index 0815a6b..7911dea 100644
--- a/docs/nu-git-manager-sugar/git/prompt/setup.md
+++ b/docs/nu-git-manager-sugar/git/prompt/setup.md
@@ -1,4 +1,4 @@
-# `setup` (`nu-git-manager-sugar git prompt`)
+# `setup` from `nu-git-manager-sugar git prompt` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/git/prompt.nu#L62))
 setup the Git prompt of NGM
 
 the different sections of the prompt are the following, in order and separated by a single space:
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
index 635b72e..1971150 100644
--- a/docs/nu-git-manager-sugar/github/gm-gh-pr-checkout.md
+++ b/docs/nu-git-manager-sugar/github/gm-gh-pr-checkout.md
@@ -1,4 +1,4 @@
-# `gm gh pr checkout` (`nu-git-manager-sugar github`)
+# `gm gh pr checkout` from `nu-git-manager-sugar github` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/github.nu#L211))
 checkout one of the repo's PR interactively
 
 
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
index 20209a1..2d49472 100644
--- a/docs/nu-git-manager-sugar/github/gm-gh-query-api.md
+++ b/docs/nu-git-manager-sugar/github/gm-gh-query-api.md
@@ -1,4 +1,4 @@
-# `gm gh query-api` (`nu-git-manager-sugar github`)
+# `gm gh query-api` from `nu-git-manager-sugar github` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/github.nu#L83))
 query the GitHub API for any end point
 
 > :bulb: **Note**  
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
index fc427a8..198084a 100644
--- a/docs/nu-git-manager-sugar/github/gm-gh-query-releases.md
+++ b/docs/nu-git-manager-sugar/github/gm-gh-query-releases.md
@@ -1,4 +1,4 @@
-# `gm gh query-releases` (`nu-git-manager-sugar github`)
+# `gm gh query-releases` from `nu-git-manager-sugar github` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/github.nu#L188))
 list the releases of a GitHub repository
 
 ## Examples
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
index 9b8ba73..aa80368 100644
--- a/docs/nu-git-manager-sugar/github/gm-gh-query-user.md
+++ b/docs/nu-git-manager-sugar/github/gm-gh-query-user.md
@@ -1,4 +1,4 @@
-# `gm gh query-user` (`nu-git-manager-sugar github`)
+# `gm gh query-user` from `nu-git-manager-sugar github` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/github.nu#L203))
 get information about a GitHub user
 
 ## Examples:
diff --git a/docs/nu-git-manager/gm-clean.md b/docs/nu-git-manager/gm-clean.md
index ca952d4..6feea31 100644
--- a/docs/nu-git-manager/gm-clean.md
+++ b/docs/nu-git-manager/gm-clean.md
@@ -1,4 +1,4 @@
-# `gm clean` (`nu-git-manager`)
+# `gm clean` from `nu-git-manager` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager/nu-git-manager/mod.nu#L552))
 clean the store
 
 this command will mainly remove empty directory recursively.
diff --git a/docs/nu-git-manager/gm-clone.md b/docs/nu-git-manager/gm-clone.md
index b9605ff..bad95f2 100644
--- a/docs/nu-git-manager/gm-clone.md
+++ b/docs/nu-git-manager/gm-clone.md
@@ -1,4 +1,4 @@
-# `gm clone` (`nu-git-manager`)
+# `gm clone` from `nu-git-manager` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager/nu-git-manager/mod.nu#L88))
 clone a remote Git repository into your local store
 
 will give a nice error if the repository is already in the local store.
diff --git a/docs/nu-git-manager/gm-list.md b/docs/nu-git-manager/gm-list.md
index 7bb0e77..f7bba00 100644
--- a/docs/nu-git-manager/gm-list.md
+++ b/docs/nu-git-manager/gm-list.md
@@ -1,4 +1,4 @@
-# `gm list` (`nu-git-manager`)
+# `gm list` from `nu-git-manager` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager/nu-git-manager/mod.nu#L216))
 list all the local repositories in your local store
 
 **/!\\** this command will return sanitized paths. **/!\\**
diff --git a/docs/nu-git-manager/gm-remove.md b/docs/nu-git-manager/gm-remove.md
index 832972b..19cc616 100644
--- a/docs/nu-git-manager/gm-remove.md
+++ b/docs/nu-git-manager/gm-remove.md
@@ -1,4 +1,4 @@
-# `gm remove` (`nu-git-manager`)
+# `gm remove` from `nu-git-manager` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager/nu-git-manager/mod.nu#L354))
 remove one of the repositories from your local store
 
 ## Examples
diff --git a/docs/nu-git-manager/gm-squash-forks.md b/docs/nu-git-manager/gm-squash-forks.md
index 91973ab..1366ca0 100644
--- a/docs/nu-git-manager/gm-squash-forks.md
+++ b/docs/nu-git-manager/gm-squash-forks.md
@@ -1,4 +1,4 @@
-# `gm squash-forks` (`nu-git-manager`)
+# `gm squash-forks` from `nu-git-manager` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager/nu-git-manager/mod.nu#L475))
 squash multi-directory forks into a single repo
 
 Here, two forks are defined as *two non-grafted repositories that share the same initial commit,
diff --git a/docs/nu-git-manager/gm-status.md b/docs/nu-git-manager/gm-status.md
index 2cb02f8..3238f7a 100644
--- a/docs/nu-git-manager/gm-status.md
+++ b/docs/nu-git-manager/gm-status.md
@@ -1,4 +1,4 @@
-# `gm status` (`nu-git-manager`)
+# `gm status` from `nu-git-manager` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager/nu-git-manager/mod.nu#L284))
 get current status about the repositories managed by NGM
 
 **/!\\** `$.root.path` and `$.cache.path` will be sanitized **/!\\**
diff --git a/docs/nu-git-manager/gm-update-cache.md b/docs/nu-git-manager/gm-update-cache.md
index 83f6b33..081c6f5 100644
--- a/docs/nu-git-manager/gm-update-cache.md
+++ b/docs/nu-git-manager/gm-update-cache.md
@@ -1,4 +1,4 @@
-# `gm update-cache` (`nu-git-manager`)
+# `gm update-cache` from `nu-git-manager` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager/nu-git-manager/mod.nu#L317))
 update the local cache of repositories
 
 ## Examples
diff --git a/docs/nu-git-manager/gm.md b/docs/nu-git-manager/gm.md
index 5188313..64bff0d 100644
--- a/docs/nu-git-manager/gm.md
+++ b/docs/nu-git-manager/gm.md
@@ -1,4 +1,4 @@
-# `gm` (`nu-git-manager`)
+# `gm` from `nu-git-manager` (see [source](https://github.com/amtoine/nu-git-manager/blob/main/pkgs/nu-git-manager/nu-git-manager/mod.nu#L55))
 manage your Git repositories with the main command of NGM
 
 ### the location for the store
diff --git a/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/git/prompt.nu b/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/git/prompt.nu
index 22248f5..64354b0 100644
--- a/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/git/prompt.nu
+++ b/pkgs/nu-git-manager-sugar/nu-git-manager-sugar/git/prompt.nu
@@ -59,7 +59,7 @@ const DEFAULT_PROMPT_INDICATORS = {
 #     }
 # }
 # ```
-export def --env setup [
+export def --env "setup" [
     --indicators = $DEFAULT_PROMPT_INDICATORS,
     --duration-threshold: duration = 1sec  # the threshold above which the command duration is shown
 ]: nothing -> nothing {
diff --git a/toolkit.nu b/toolkit.nu
index a387848..30af921 100644
--- a/toolkit.nu
+++ b/toolkit.nu
@@ -163,6 +163,23 @@ def run-nu [code: string]: nothing -> any {
     ^$nu.current-exe --no-config-file --commands ($code ++ " | to nuon") | from nuon
 }
 
+def rg [root: path, pattern: string]: nothing -> table<file: path, line: int, match: string> {
+    ls ($root | path join "**" "*")
+        | where type == file
+        | get name
+        | wrap file
+        | insert match {|it|
+            open $it.file --raw
+                | lines
+                | enumerate
+                | rename line match
+                | update line { $in + 1 }
+                | find --regex $pattern
+        }
+        | where not ($it.match | is-empty)
+        | flatten --all
+}
+
 def document-command [
     args: record<module_name: string, full_module_name_with_leading_path: string, root: path>
 ]: string -> string {
@@ -181,8 +198,17 @@ def document-command [
 
     let signatures = $help.signatures | transpose | get column1
 
+    let res = rg $args.root $'export def.*"($command)"'
+    let res = match ($res | length) {
+        0 => { error make --unspanned { msg: $"no match for command `($command)`" } },
+        1 => { $res.0 | into record },
+        _ => { error make --unspanned { msg: $"too many matches for command `($command)`" } },
+    }
+
+    let source = $"https://github.com/amtoine/nu-git-manager/blob/main/($res.file | path relative-to $args.root)#L($res.line)"
+
     let page = [
-        $"# `($command)` \(`($args.module_name)`\)",
+        $"# `($command)` from `($args.module_name)` \(see [source]\(($source)\)\)",
         $help.usage,
         "",
         $help.extra_usage,