Skip to content

Commit 1a9c0d9

Browse files
amtoineamtoine
authored
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
1 parent 2dc21d5 commit 1a9c0d9

35 files changed

+1021
-28
lines changed

‎.github/workflows/check-documentation.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: Checking the documentation
2+
3+
on:
4+
pull_request:
5+
branches: [main]
6+
types: [opened, synchronize, reopened]
7+
push:
8+
branches:
9+
- main
10+
- nightly
11+
12+
jobs:
13+
check-merge:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- name: Checking out repository
17+
uses: actions/checkout@v3
18+
19+
- uses: hustcer/[email protected]
20+
with:
21+
version: "0.87.0"
22+
23+
- name: Check the documentation
24+
shell: nu {0}
25+
run: |
26+
nu --commands $"
27+
use ($env.PWD)/toolkit.nu
28+
toolkit doc
29+
if not \(git status --short | lines | is-empty\) {
30+
error make --unspanned {
31+
msg: $'status is non-empty: \(git status --short | lines\)'
32+
}
33+
}
34+
"

‎README.md‎

Lines changed: 6 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -54,36 +54,21 @@ nupm install --path --force nu-git-manager
5454
5555
## :gear: usage [[toc](#table-of-content)]
5656
in your `config.nu` you can add the following to load `nu-git-manager` modules:
57-
```nu
57+
```nushell
5858
# load the main `gm` command
5959
use nu-git-manager *
6060
6161
# the following are non-essential modules
62-
use nu-git-manager-sugar git # augment Git with custom commands
63-
use nu-git-manager-sugar gh # load commands to interact with *GitHub*
64-
use nu-git-manager-sugar gist # load commands to interact with *GitHub* gists
62+
use nu-git-manager-sugar extra * # augment `gm` with additional commands
6563
```
6664

65+
> **Note**
66+
> please have a look at the [documentation of NGM](./docs/index.md) for more modules and commands
67+
6768
then you have access to the whole `nu-git-manager` suite :partying_face:
6869

6970
### :pray: getting help [[toc](#table-of-content)]
70-
do not hesitate to run one of the following to have more information about what `nu-git-manager` has to offer :thumbsup:
71-
```nu
72-
help gm
73-
# or
74-
gm
75-
```
76-
```nu
77-
help modules git
78-
```
79-
```nu
80-
help modules gh
81-
```
82-
```nu
83-
help modules gist
84-
# or
85-
gist
86-
```
71+
please have a look at the [documentation of NGM](./docs/index.md)
8772

8873
## :exclamation: some ideas of advanced (?) usage [[toc](#table-of-content)]
8974
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‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
## Modules
2+
- [`nu-git-manager`](./nu-git-manager/index.md)
3+
- [`nu-git-manager-sugar`](./nu-git-manager-sugar/index.md)
4+
5+
## Commands
6+
- [`gm`](nu-git-manager/gm.md)
7+
- [`gm clean`](nu-git-manager/gm-clean.md)
8+
- [`gm clone`](nu-git-manager/gm-clone.md)
9+
- [`gm list`](nu-git-manager/gm-list.md)
10+
- [`gm remove`](nu-git-manager/gm-remove.md)
11+
- [`gm squash-forks`](nu-git-manager/gm-squash-forks.md)
12+
- [`gm status`](nu-git-manager/gm-status.md)
13+
- [`gm update-cache`](nu-git-manager/gm-update-cache.md)
14+
- [`gm report`](nu-git-manager-sugar/extra/gm-report.md)
15+
- [`gm repo branch interactive-delete`](nu-git-manager-sugar/git/gm-repo-branch-interactive-delete.md)
16+
- [`gm repo branch wipe`](nu-git-manager-sugar/git/gm-repo-branch-wipe.md)
17+
- [`gm repo branches`](nu-git-manager-sugar/git/gm-repo-branches.md)
18+
- [`gm repo compare`](nu-git-manager-sugar/git/gm-repo-compare.md)
19+
- [`gm repo fetch branch`](nu-git-manager-sugar/git/gm-repo-fetch-branch.md)
20+
- [`gm repo get commit`](nu-git-manager-sugar/git/gm-repo-get-commit.md)
21+
- [`gm repo goto root`](nu-git-manager-sugar/git/gm-repo-goto-root.md)
22+
- [`gm repo is-ancestor`](nu-git-manager-sugar/git/gm-repo-is-ancestor.md)
23+
- [`gm repo ls`](nu-git-manager-sugar/git/gm-repo-ls.md)
24+
- [`gm repo remote list`](nu-git-manager-sugar/git/gm-repo-remote-list.md)
25+
- [`gm repo switch`](nu-git-manager-sugar/git/gm-repo-switch.md)
26+
- [`setup`](nu-git-manager-sugar/git/prompt/setup.md)
27+
- [`gm gh pr checkout`](nu-git-manager-sugar/github/gm-gh-pr-checkout.md)
28+
- [`gm gh query-api`](nu-git-manager-sugar/github/gm-gh-query-api.md)
29+
- [`gm gh query-releases`](nu-git-manager-sugar/github/gm-gh-query-releases.md)
30+
- [`gm gh query-user`](nu-git-manager-sugar/github/gm-gh-query-user.md)

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# `nu-git-manager-sugar extra gm report`
2+
## Description
3+
get a full report about the local store of repositories
4+
5+
6+
7+
## Parameters
8+
9+
10+
## Signatures
11+
| input | output |
12+
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
13+
| `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‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Module `nu-git-manager-sugar extra`
2+
## Description
3+
4+
5+
## Commands
6+
- [`gm report`](gm-report.md)

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# `nu-git-manager-sugar git gm repo branch interactive-delete`
2+
## Description
3+
remove a branch interactively
4+
5+
6+
7+
## Parameters
8+
9+
10+
## Signatures
11+
| input | output |
12+
| ----- | ------ |
13+
| `any` | `any` |

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

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# `nu-git-manager-sugar git gm repo branch wipe`
2+
## Description
3+
wipe a branch completely, i.e. both locally and remotely
4+
5+
6+
7+
## Parameters
8+
- parameter_name: branch
9+
- parameter_type: positional
10+
- syntax_shape: string
11+
- is_optional: false
12+
- description: the branch to wipe
13+
---
14+
- parameter_name: remote
15+
- parameter_type: positional
16+
- syntax_shape: string
17+
- is_optional: false
18+
- description: the remote to push to
19+
20+
## Signatures
21+
| input | output |
22+
| ----- | ------ |
23+
| `any` | `any` |

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

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# `nu-git-manager-sugar git gm repo branches`
2+
## Description
3+
inspect local branches
4+
5+
> **Note**
6+
> in the following, a "*dangling*" branch refers to a branch that does not have any remote
7+
> counterpart, i.e. it's a purely local branch.
8+
9+
# Examples
10+
list branches and their associated remotes
11+
> gm repo branches
12+
13+
clean all dangling branches
14+
> gm repo branches --clean
15+
16+
## Parameters
17+
- parameter_name: clean
18+
- parameter_type: switch
19+
- is_optional: true
20+
- description: clean all dangling branches
21+
22+
## Signatures
23+
| input | output |
24+
| --------- | ---------------------------------------------- |
25+
| `nothing` | `table<branch: string, remotes: list<string>>` |

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

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# `nu-git-manager-sugar git gm repo compare`
2+
## Description
3+
compare the changes between two revisions, from a target to the "head"
4+
5+
6+
7+
## Parameters
8+
- parameter_name: target
9+
- parameter_type: positional
10+
- syntax_shape: string
11+
- is_optional: false
12+
- description: the target to compare from
13+
---
14+
- parameter_name: head
15+
- parameter_type: named
16+
- syntax_shape: string
17+
- is_optional: true
18+
- description: the "head" to use for the comparison
19+
- parameter_default: HEAD
20+
21+
## Signatures
22+
| input | output |
23+
| ----- | ------ |
24+
| `any` | `any` |

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

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# `nu-git-manager-sugar git gm repo fetch branch`
2+
## Description
3+
fetch a remote branch locally, without pulling down the whole remote
4+
5+
6+
7+
## Parameters
8+
- parameter_name: remote
9+
- parameter_type: positional
10+
- syntax_shape: string
11+
- is_optional: false
12+
- description: the branch to fetch
13+
---
14+
- parameter_name: branch
15+
- parameter_type: positional
16+
- syntax_shape: string
17+
- is_optional: false
18+
- description: the remote to fetch the branch from
19+
---
20+
- parameter_name: strategy
21+
- parameter_type: named
22+
- syntax_shape: string
23+
- is_optional: true
24+
- description: the merge strategy to use
25+
- parameter_default: none
26+
27+
## Signatures
28+
| input | output |
29+
| ----- | ------ |
30+
| `any` | `any` |

0 commit comments

Comments
 (0)