From c1016e9988e52ccb735216a042cdb4e2f6d9e502 Mon Sep 17 00:00:00 2001 From: Antoine Stevan <44101798+amtoine@users.noreply.github.com> Date: Fri, 26 Jan 2024 19:15:36 +0100 Subject: [PATCH] make the command parameters in the documentation pretty (#169) just some polish on the style for the command parameters --- .../git/gm-repo-bisect.md | 27 ++-------- .../git/gm-repo-branch-wipe.md | 14 ++---- .../git/gm-repo-branches.md | 6 +-- .../git/gm-repo-compare.md | 15 ++---- .../git/gm-repo-fetch-branch.md | 25 ++-------- .../git/gm-repo-get-commit.md | 8 +-- .../git/gm-repo-is-ancestor.md | 14 ++---- docs/nu-git-manager-sugar/git/gm-repo-ls.md | 7 +-- .../nu-git-manager-sugar/git/gm-repo-query.md | 7 +-- docs/nu-git-manager-sugar/git/prompt/setup.md | 15 ++---- .../github/gm-gh-query-api.md | 27 ++-------- .../github/gm-gh-query-releases.md | 21 ++------ .../github/gm-gh-query-user.md | 13 ++--- docs/nu-git-manager/gm-clean.md | 6 +-- docs/nu-git-manager/gm-clone.md | 50 +++---------------- docs/nu-git-manager/gm-list.md | 6 +-- docs/nu-git-manager/gm-remove.md | 19 ++----- docs/nu-git-manager/gm-squash-forks.md | 7 +-- toolkit.nu | 35 +++++++++---- 19 files changed, 84 insertions(+), 238 deletions(-) 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 43cc174..acedd59 100644 --- a/docs/nu-git-manager-sugar/git/gm-repo-bisect.md +++ b/docs/nu-git-manager-sugar/git/gm-repo-bisect.md @@ -19,28 +19,11 @@ gm repo bisect --good $good --bad $bad --no-check $test ``` ## Parameters -- parameter_name: test -- parameter_type: positional -- syntax_shape: closure() -- is_optional: false -- description: the code to run to check a given revision, should return a non-zero exit code for bad revisions ---- -- parameter_name: good -- parameter_type: named -- syntax_shape: string -- is_optional: true -- description: the initial known "good" revision ---- -- parameter_name: bad -- parameter_type: named -- syntax_shape: string -- is_optional: true -- description: the initial known "bad" revision ---- -- parameter_name: no-check -- parameter_type: switch -- is_optional: true -- description: don't check if `--good` and `--bad` are indeed "good" and "bad" +- `test` <`closure()`>: the code to run to check a given revision, should return a non-zero exit code for bad revisions +- `--good` <`string`>: the initial known "good" revision +- `--bad` <`string`>: the initial known "bad" revision +- `--no-check` <`bool`>: don't check if `--good` and `--bad` are indeed "good" and "bad" + ## Signatures | input | output | 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 2905a6f..1883f22 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 @@ -4,17 +4,9 @@ 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 +- `branch` <`string`>: the branch to wipe +- `remote` <`string`>: the remote to push to + ## Signatures | input | output | 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 c87f1f5..4f77b4e 100644 --- a/docs/nu-git-manager-sugar/git/gm-repo-branches.md +++ b/docs/nu-git-manager-sugar/git/gm-repo-branches.md @@ -17,10 +17,8 @@ gm repo branches --clean ``` ## Parameters -- parameter_name: clean -- parameter_type: switch -- is_optional: true -- description: clean all dangling branches +- `--clean` <`bool`>: clean all dangling branches + ## Signatures | input | output | 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 a002add..442d53c 100644 --- a/docs/nu-git-manager-sugar/git/gm-repo-compare.md +++ b/docs/nu-git-manager-sugar/git/gm-repo-compare.md @@ -4,18 +4,9 @@ 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 +- `target` <`string`>: the target to compare from +- `--head` <`string`> = `HEAD`: the "head" to use for the comparison + ## Signatures | input | output | 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 744a1bd..3dab191 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 @@ -4,27 +4,10 @@ fetch a remote branch locally, without pulling down the whole remote ## Parameters -- parameter_name: remote -- parameter_type: positional -- syntax_shape: completable -- is_optional: false -- description: the branch to fetch -- custom_completion: get-remotes ---- -- parameter_name: branch -- parameter_type: positional -- syntax_shape: completable -- is_optional: false -- description: the remote to fetch the branch from -- custom_completion: get-branches ---- -- parameter_name: strategy -- parameter_type: named -- syntax_shape: completable -- is_optional: true -- description: the merge strategy to use -- custom_completion: get-strategies -- parameter_default: none +- `remote` <`string@get-remotes`>: the branch to fetch +- `branch` <`string@get-branches`>: the remote to fetch the branch from +- `--strategy` <`string@get-strategies`> = `none`: the merge strategy to use + ## Signatures | input | output | 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 b8a211c..52368a0 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 @@ -13,12 +13,8 @@ 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 +- `revision?` <`string`> = `HEAD`: the revision to get the hash of + ## Signatures | input | output | 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 2524233..6ab09ad 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 @@ -19,17 +19,9 @@ 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 +- `a` <`string`>: the base commit-ish revision +- `b` <`string`>: the *head* commit-ish revision + ## Signatures | input | output | 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 4d8f9dc..75dabdf 100644 --- a/docs/nu-git-manager-sugar/git/gm-repo-ls.md +++ b/docs/nu-git-manager-sugar/git/gm-repo-ls.md @@ -4,11 +4,8 @@ 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 `.`) +- `repo?` <`path`>: the path to the repo (defaults to `.`) + ## Signatures | input | output | 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 148588b..05c1c57 100644 --- a/docs/nu-git-manager-sugar/git/gm-repo-query.md +++ b/docs/nu-git-manager-sugar/git/gm-repo-query.md @@ -25,11 +25,8 @@ gm repo query diffs ``` ## Parameters -- parameter_name: table -- parameter_type: positional -- syntax_shape: completable -- is_optional: false -- custom_completion: git-query-tables +- `table` <`string@git-query-tables`>: + ## Signatures | input | output | diff --git a/docs/nu-git-manager-sugar/git/prompt/setup.md b/docs/nu-git-manager-sugar/git/prompt/setup.md index 7911dea..8d6c46b 100644 --- a/docs/nu-git-manager-sugar/git/prompt/setup.md +++ b/docs/nu-git-manager-sugar/git/prompt/setup.md @@ -55,18 +55,9 @@ export-env { ``` ## Parameters -- parameter_name: indicators -- parameter_type: named -- syntax_shape: record> -- 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 +- `--indicators` <`record>`> = `{plain: > , vi: {insert: : , normal: > }}`: +- `--duration-threshold` <`duration`> = `1sec`: the threshold above which the command duration is shown + ## Signatures | input | output | 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 2d49472..4c71638 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 @@ -24,28 +24,11 @@ you shall not rebase in the middle of a PR review nor close other's review threa ``` ## 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` +- `end_point` <`string`>: the end point in the GitHub API to query +- `--page-size` <`int`> = `100`: the size of each page +- `--no-paginate` <`bool`>: do not paginate the API, useful when getting a single record +- `--no-gh` <`bool`>: force to use `http get` instead of `gh` + ## Signatures | input | output | 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 198084a..20a6908 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 @@ -12,23 +12,10 @@ gm gh query-releases "nushell/nushell" ``` ## 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` +- `repo` <`string`>: the GitHub repository to query the releases of +- `--page-size` <`int`> = `100`: the size of each page +- `--no-gh` <`bool`>: force to use `http get` instead of `gh` + ## Signatures | input | output | 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 aa80368..c3622ec 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 @@ -8,16 +8,9 @@ gm gh query-user amtoine | get avatar_url | http get $in | save --force amtoine. ``` ## 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` +- `user` <`string`>: the user to query information about +- `--no-gh` <`bool`>: force to use `http get` instead of `gh` + ## Signatures | input | output | diff --git a/docs/nu-git-manager/gm-clean.md b/docs/nu-git-manager/gm-clean.md index 6feea31..786d8c7 100644 --- a/docs/nu-git-manager/gm-clean.md +++ b/docs/nu-git-manager/gm-clean.md @@ -17,10 +17,8 @@ gm clean --list ``` ## Parameters -- parameter_name: list -- parameter_type: switch -- is_optional: true -- description: only list without cleaning +- `--list` <`bool`>: only list without cleaning + ## Signatures | input | output | diff --git a/docs/nu-git-manager/gm-clone.md b/docs/nu-git-manager/gm-clone.md index bad95f2..2d110f8 100644 --- a/docs/nu-git-manager/gm-clone.md +++ b/docs/nu-git-manager/gm-clone.md @@ -30,48 +30,14 @@ 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 -- 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 -- 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 +- `url` <`string`>: the URL to the repository to clone, supports HTTPS and SSH links, as well as references ending in `.git` or starting with `git@` +- `--remote` <`string`> = `origin`: the name of the remote to setup +- `--ssh` <`bool`>: setup the remote to use the SSH protocol both to FETCH and to PUSH +- `--fetch` <`string@git-protocols`>: setup the FETCH protocol explicitely, will overwrite `--ssh` for FETCH +- `--push` <`string@git-protocols`>: setup the PUSH protocol explicitely, will overwrite `--ssh` for PUSH +- `--bare` <`bool`>: clone the repository as a "bare" project +- `--depth` <`int`>: the depth at which to clone the repository + ## Signatures | input | output | diff --git a/docs/nu-git-manager/gm-list.md b/docs/nu-git-manager/gm-list.md index f7bba00..184466b 100644 --- a/docs/nu-git-manager/gm-list.md +++ b/docs/nu-git-manager/gm-list.md @@ -20,10 +20,8 @@ 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 +- `--full-path` <`bool`>: show the full path instead of only the "owner + group + repo" name + ## Signatures | input | output | diff --git a/docs/nu-git-manager/gm-remove.md b/docs/nu-git-manager/gm-remove.md index 19cc616..87072f3 100644 --- a/docs/nu-git-manager/gm-remove.md +++ b/docs/nu-git-manager/gm-remove.md @@ -23,21 +23,10 @@ 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 +- `pattern?` <`string`>: a pattern to restrict the choices +- `--fuzzy` <`bool`>: remove after fuzzy-finding the repo(s) to clean +- `--no-confirm` <`bool`>: do not ask for confirmation: useful in scripts but requires a single match + ## Signatures | input | output | diff --git a/docs/nu-git-manager/gm-squash-forks.md b/docs/nu-git-manager/gm-squash-forks.md index 1366ca0..513eaa5 100644 --- a/docs/nu-git-manager/gm-squash-forks.md +++ b/docs/nu-git-manager/gm-squash-forks.md @@ -32,11 +32,8 @@ gm squash-forks --non-interactive-preselect { ``` ## Parameters -- parameter_name: non-interactive-preselect -- parameter_type: named -- syntax_shape: record -- is_optional: true -- description: the non-interactive preselection record, see documentation above +- `--non-interactive-preselect` <`record`> = `{}`: the non-interactive preselection record, see documentation above + ## Signatures | input | output | diff --git a/toolkit.nu b/toolkit.nu index f449c9c..a8baefb 100644 --- a/toolkit.nu +++ b/toolkit.nu @@ -220,17 +220,32 @@ def document-command [ ( $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" + | each {|p| + let opt = if $p.is_optional { "?" } else { "" } + let cmp = if $p.custom_completion != "" { + $"@($p.custom_completion)" + } else { + "" + } + let type = $p.syntax_shape + | default "" + | str replace --regex '^completable<(.*)>' '$1' + let default = if $p.parameter_default != null { + $" = `($p.parameter_default)`" + } else { + "" + } + let short = if $p.short_flag != null { $" \(`-($p.short_flag)`\)" } else { "" } + let name = $p.parameter_name + let desc = $p.description + + match $p.parameter_type { + "positional" => $"- `($name)($opt)` <`($type)($cmp)`>($default): ($desc)", + "switch" => $"- `--($name)`($short) <`bool($cmp)`>($default): ($desc)", + "named" => $"- `--($name)`($short) <`($type)($cmp)`>($default): ($desc)", + } } - | str join "\n---\n" + | to text ), "", $"## Signatures",