Merge pull request #2275 from rsteube/doc-creating-completers

doc: creating completers

completers/ln_completer/main.go

@@ -1,6 +1,6 @@
 package main
 
-import "github.com/rsteube/carapace-bin/completers/ln_completer/cmd"
+import "github.com/rsteube/carapace-bin/completers/manually_completer/cmd"
 
 func main() {
 	cmd.Execute()

docs/src/SUMMARY.md

@@ -24,7 +24,13 @@
     - [Project Layout](./development/projectLayout.md)
     - [Build](./development/build.md)
     - [Docker](./development/docker.md)
-    - [Creating completers](./development/creatingCompleters.md)
+    - [Creating Completers](./development/creatingCompleters.md)
+      - [Manually](./development/creatingCompleters/manually.md)
+      - [Parsing](./development/creatingCompleters/parsing.md)
+      - [Scraping](./development/creatingCompleters/scraping.md)
+    - [Updating Completers](./development/updatingCompleters.md)
+    - [Best Practices](./development/bestPractices.md)
+      - [Coupled Actions](./development/bestPractices/coupledActions.md)
     - [Tools](./development/tools.md)
       - [carapace-fmt](./development/tools/carapace-fmt.md)
       - [carapace-lint](./development/tools/carapace-lint.md)

docs/src/development/bestPractices.md

@@ -0,0 +1 @@
+# Best Practices

docs/src/development/bestPractices/coupledActions.md

@@ -0,0 +1,43 @@
+# Coupled Actions
+
+Use coupled actions to avoid repetition.
+
+Sometimes an [Action] depends on the same flag values for multiple subcommands.
+Since [ActionCallback] is needed to access these the code can become a bit cumbersome and bloated.
+
+```go
+carapace.Gen(get_allCmd).PositionalCompletion(
+	carapace.ActionCallback(func(c carapace.Context) carapace.Action {
+		return helm.ActionReleases(helm.ReleasesOpts{
+			Namespace:   rootCmd.Flag("namespace").Value.String(),
+			KubeContext: rootCmd.Flag("kube-context").Value.String(),
+		})
+	}),
+)
+```
+
+An alternative to this is creating a local [Action] that is coupled to the command.
+Meaning, passing it the command and expecting specific flags to be present.
+
+```go
+// completers/helm_completer/cmd/action/release.go
+func ActionReleases(cmd *cobra.Command) carapace.Action {
+	return carapace.ActionCallback(func(c carapace.Context) carapace.Action {
+		return helm.ActionReleases(helm.ReleasesOpts{
+			Namespace:   cmd.Root().Flag("namespace").Value.String(),
+			KubeContext: cmd.Root().Flag("kube-context").Value.String(),
+		})
+	})
+}
+```
+
+Thus the call becomes quite compact.
+
+```go
+carapace.Gen(get_allCmd).PositionalCompletion(
+	action.ActionReleases(get_allCmd),
+)
+```
+
+[Action]:https://rsteube.github.io/carapace/carapace/action.html
+[ActionCallback]:https://rsteube.github.io/carapace/carapace/defaultActions/actionCallback.html

docs/src/development/build.md

@@ -35,7 +35,6 @@ Completers can also be built (and thus maintained) separately.
 ```sh
 cd completers/ln_completer
 go install -ldflags="-s -w"
-ln_completer _carapace
 ```
 
 ![](./build-separate.cast)

docs/src/development/creatingCompleters/manually.md

@@ -0,0 +1,32 @@
+# Manually
+
+- Copy a basic completer for simplicity.
+
+```sh
+cp -r completers/ln_completer completers/manually_completer
+```
+
+- Update the package name in `main.go`.
+
+```diff
+-import "github.com/rsteube/carapace-bin/completers/ln_completer/cmd"
++import "github.com/rsteube/carapace-bin/completers/manually_completer/cmd"
+```
+
+- Create the root command.
+
+```sh
+echo | carapace-parse -n manually > root.go
+```
+
+- Add subcommands.
+
+```sh
+echo | carapace-parse -n subcommand -p root > subcommand.go
+```
+
+- Define flags and completions.
+
+- [Build and install](../build.md#development).
+
+![](./manually.cast)

docs/src/development/creatingCompleters/parsing.md

@@ -0,0 +1 @@
+# Parsing

docs/src/development/creatingCompleters/scraping.md

@@ -0,0 +1 @@
+# Scraping

docs/src/development/projectLayout.md

@@ -5,7 +5,7 @@
 ├── cmd
 │  ├── carapace # main application
 │  ├── carapace-fmt # simple formatter
-│  ├── carapace-generate # called by `go generate`
+│  ├── carapace-generate # executed by `go generate`
 │  ├── carapace-lint # simple linter
 │  ├── carapace-parse # simple help output parser
 │  └── carapace-shim # binary for runnable specs in windows
@@ -16,12 +16,12 @@
 ├── completers_release # optimized completers
 ├── dist # goreleaser dist folder
 ├── docs # documentation
-├── internal # some internal packages
+├── internal # internal packages
 └── pkg # public packages
    ├── actions # shared actions that are also exposed as macros
    │  └── tools # shared actions specific to tools
    ├── conditions # conditions for environment variable completion
    ├── env # environment variables
    ├── styles # style configurations
-   └── util # some util functions
+   └── util # util functions
 ```

docs/src/development/updatingCompleters.md

@@ -0,0 +1 @@
+# Updating Completers