Merge pull request #3160 from carapace-sh/doc-groups

doc: added groups

Author: rsteube

.docker/carapace.yaml

@@ -13,7 +13,15 @@ services:
     command: sh -c 'cp -r /carapace-bin /build && cd /build/ && goreleaser release --snapshot --clean --skip publish --parallelism 1'
     volumes:
       - '..:/carapace-bin:ro'
-      
+
+  docs:
+    image: ghcr.io/carapace-sh/mdbook:latest
+    command: mdbook serve --hostname 0.0.0.0 --dest-dir /tmp/book /docs
+    volumes:
+      - '../docs:/docs:ro'
+    ports:
+      - 3000:3000
+
   bash:
     image: ghcr.io/carapace-sh/base
     volumes:

docs/src/SUMMARY.md

@@ -6,6 +6,7 @@
   - [Setup](./setup.md)
     - [Environment](./setup/environment.md)
     - [UserConfigDir](./setup/userConfigDir.md)
+  - [Groups](./groups.md)
   - [Completers](./completers.md)
   - [Style](./style.md)
   - [Bridges](./bridges.md)

docs/src/groups.md

@@ -0,0 +1,64 @@
+> unreleased
+
+# Groups
+
+Completers are organized into **groups**.
+
+- `android` termux completers
+- `bridge` bridged completers
+- `bsd` bsd-like completers
+- `common` common completers
+- `darwin` macos completers
+- `linux` linux completers
+- `unix` unix-like completers
+- `user` user specs
+- `system` system specs
+- `windows` windows completers
+
+You can **list** available completers of a **group** with `carapace --list @{group}`.
+
+![](./groups/group.cast)
+
+> Binaries only contain **relevant groups** unless built with the [build tag](https://www.digitalocean.com/community/tutorials/customizing-go-binaries-with-build-tags) `force_all`.
+
+## Priority
+
+Multiple **groups** providing a completer for a command are ordered by **priority**.
+
+- darwin
+  1. `user`
+  1. `system`
+  1. `darwin`
+  1. `bsd`
+  1. `unix`
+  1. `common`
+  1. `bridge`
+
+- linux
+  1. `user`
+  1. `system`
+  1. `linux`
+  1. `unix`
+  1. `common`
+  1. `bridge`
+
+- termux
+  1. `user`
+  1. `system`
+  1. `android`
+  1. `linux`
+  1. `unix`
+  1. `common`
+  1. `bridge`
+
+- windows
+  1. `user`
+  1. `system`
+  1. `windows`
+  1. `common`
+  1. `bridge`
+
+
+You can **list** available completers of a **command** with `carapace --list {command}`.
+
+![](./groups/priority.cast)

docs/src/groups/group.cast

@@ -28,5 +28,24 @@ commands:
 ![](./v1.x/extended.cast)
 
 
+## Groups
+
+Organized completers into [**groups**](../groups.md).
+
+- `android` termux completers
+- `bridge` bridged completers
+- `bsd` bsd-like completers
+- `common` common completers
+- `darwin` macos completers
+- `linux` linux completers
+- `unix` unix-like completers
+- `user` user specs
+- `system` system specs
+- `windows` windows completers
+
+![](./v1.x/group.cast)
+
+
+
 [aws-cli]:https://github.com/aws/aws-cli
 [carapace-aws]:https://github.com/carapace-sh/carapace-aws

docs/src/groups/priority.cast

@@ -94,14 +94,14 @@ func ActionGroups(nameVariant string) carapace.Action {
 
 		descriptions := map[string]string{
 			"android": "termux completers",
-			"bridge":  "bridged completions",
+			"bridge":  "bridged completers",
 			"bsd":     "bsd-like completers",
 			"common":  "common completers",
 			"darwin":  "macos completers",
 			"linux":   "linux completers",
-			"system":  "system specs",
 			"unix":    "unix-like completers",
 			"user":    "user specs",
+			"system":  "system specs",
 			"windows": "windows completers",
 		}