From 14f8f7250e8b9d011feb5e4e266de9b06b91c469 Mon Sep 17 00:00:00 2001 From: rsteube Date: Sun, 9 Oct 2022 11:26:33 +0200 Subject: [PATCH] doc: updated bridge --- docs/src/SUMMARY.md | 1 + docs/src/spec/bride.md | 40 ++++++++++++++++++++++++++-------------- docs/src/spec/embed.md | 1 + 3 files changed, 28 insertions(+), 14 deletions(-) create mode 100644 docs/src/spec/embed.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 68901def08..560196030f 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -8,6 +8,7 @@ - [Style](./style.md) - [Spec](./spec.md) - [Bridge](./spec/bride.md) + - [Embed](./spec/embed.md) - [Examples](./spec/examples.md) - [Macros](./spec/macros.md) - [Development](./development.md) diff --git a/docs/src/spec/bride.md b/docs/src/spec/bride.md index 0679103ffd..76bb400334 100644 --- a/docs/src/spec/bride.md +++ b/docs/src/spec/bride.md @@ -1,8 +1,16 @@ # Bridge +Bridging completions from other engines for shells not natively supported by it is possible with the corresponding [Macro](./macros.md). + +> Even when the command supports your current shell it is still beneficial to bridge it as this enables [embedding](./embed.md) like `sudo [spec.name] `. +> +> It also avoids the issue of [shell startup delay] when sourcing the completion in init scripts otherwise circumvented with [lazycomplete]. +> +> However, bridging is limited to supported commands/frameworks and how well it actually works. + ## Argcomplete -[kislyuk/argcomplete] based commands can be bridged with the [bridge.Argcomplete(\)] macro: +[kislyuk/argcomplete] based commands can be bridged with the [`bridge.Argcomplete`] macro: ```yaml name: az @@ -13,7 +21,7 @@ completion: ## Carapace -[rsteube/carapace] based commands can be bridged with the [bridge.Carapace(\)] macro: +[rsteube/carapace] based commands can be bridged with the [`bridge.Carapace`] macro: ```yaml name: freckles @@ -24,7 +32,7 @@ completion: ## CarapaceBin -[Completers](../completers.md) and [Specs](../spec.md) registered in [rsteube/carapace-bin] can be bridged with the [bridge.CarapaceBin(\)] macro: +[Completers](../completers.md) and [Specs](../spec.md) registered in [rsteube/carapace-bin] can be bridged with the [`bridge.CarapaceBin`] macro: ```yaml name: gh @@ -35,7 +43,7 @@ completion: ## Click -[pallets/click] based commands can be bridged with the [bridge.Click(\)] macro: +[pallets/click] based commands can be bridged with the [`bridge.Click`] macro: ```yaml name: watson @@ -46,7 +54,7 @@ completion: ## Cobra -[spf13/cobra] based commands can be bridged with the [bridge.Cobra(\)] macro: +[spf13/cobra] based commands can be bridged with the [`bridge.Cobra`] macro: ```yaml name: kubectl @@ -57,7 +65,7 @@ completion: ## Fish -Commands registered in [fish-shell/fish-shell] can be bridged with the [bridge.Fish(\)] macro: +Commands registered in [fish-shell/fish-shell] can be bridged with the [`bridge.Fish`] macro: ```yaml name: git @@ -67,7 +75,7 @@ completion: ```` ## Posener (TODO: rename to `Complete`) -[posener/complete] based commands can be bridged with the [bridge.Posener(\)] macro: +[posener/complete] based commands can be bridged with the [`bridge.Posener`] macro: ```yaml name: vault @@ -77,23 +85,27 @@ completion: ```` +[lazycomplete]:https://github.com/rsteube/lazycomplete +[shell startup delay]:https://jzelinskie.com/posts/dont-recommend-sourcing-shell-completion/ + + [kislyuk/argcomplete]:https://github.com/kislyuk/argcomplete -[bridge.Argcomplete(\)]:https://pkg.go.dev/github.com/rsteube/carapace-bin/pkg/actions/bridge#ActionArgcomplete +[`bridge.Argcomplete`]:https://pkg.go.dev/github.com/rsteube/carapace-bin/pkg/actions/bridge#ActionArgcomplete [rsteube/carapace]:https://github.com/rsteube/carapace -[bridge.Carapace(\)]:https://pkg.go.dev/github.com/rsteube/carapace-bin/pkg/actions/bridge#ActionCarapace +[`bridge.Carapace`]:https://pkg.go.dev/github.com/rsteube/carapace-bin/pkg/actions/bridge#ActionCarapace [rsteube/carapace-bin]:https://github.com/rsteube/carapace-bin -[bridge.CarapaceBin(\)]:https://pkg.go.dev/github.com/rsteube/carapace-bin/pkg/actions/bridge#ActionCarapaceBin +[`bridge.CarapaceBin`]:https://pkg.go.dev/github.com/rsteube/carapace-bin/pkg/actions/bridge#ActionCarapaceBin [pallets/click]:https://github.com/pallets/click -[bridge.Click(\)]:https://pkg.go.dev/github.com/rsteube/carapace-bin/pkg/actions/bridge#ActionClick +[`bridge.Click`]:https://pkg.go.dev/github.com/rsteube/carapace-bin/pkg/actions/bridge#ActionClick [spf13/cobra]:https://github.com/spf13/cobra -[bridge.Cobra(\)]:https://pkg.go.dev/github.com/rsteube/carapace-bin/pkg/actions/bridge#ActionCobra +[`bridge.Cobra`]:https://pkg.go.dev/github.com/rsteube/carapace-bin/pkg/actions/bridge#ActionCobra [fish-shell/fish-shell]:https://github.com/fish-shell/fish-shell -[bridge.Fish(\)]:https://pkg.go.dev/github.com/rsteube/carapace-bin/pkg/actions/bridge#ActionFish +[`bridge.Fish`]:https://pkg.go.dev/github.com/rsteube/carapace-bin/pkg/actions/bridge#ActionFish [posener/complete]:https://github.com/posener/complete -[bridge.Posener(\)]:https://pkg.go.dev/github.com/rsteube/carapace-bin/pkg/actions/bridge#ActionPosener +[`bridge.Posener`]:https://pkg.go.dev/github.com/rsteube/carapace-bin/pkg/actions/bridge#ActionPosener diff --git a/docs/src/spec/embed.md b/docs/src/spec/embed.md new file mode 100644 index 0000000000..1dc5e54ec0 --- /dev/null +++ b/docs/src/spec/embed.md @@ -0,0 +1 @@ +# Embed