fix: cli docs (#795)

.github/workflows/parallel-tests.yaml

@@ -144,6 +144,7 @@ jobs:
       - name: Run e2e vendor tests
         run: |
           build/uds run test:vendor
+          build/uds run test:completion
 
       - name: Save logs
         if: always()

docs/command-reference/uds_completion.md

@@ -38,6 +38,5 @@ See each sub-command's help for details on how to use the generated script.
 * [uds](/cli/command-reference/uds/)	 - CLI for UDS Bundles
 * [uds completion bash](/cli/command-reference/uds_completion_bash/)	 - Generate the autocompletion script for bash
 * [uds completion fish](/cli/command-reference/uds_completion_fish/)	 - Generate the autocompletion script for fish
-* [uds completion powershell](/cli/command-reference/uds_completion_powershell/)	 - Generate the autocompletion script for powershell
 * [uds completion zsh](/cli/command-reference/uds_completion_zsh/)	 - Generate the autocompletion script for zsh
 

docs/schema-validation.md

@@ -1,5 +1,5 @@
 ---
-title: UDS Runner
+title: Schema
 type: docs
 weight: 5
 ---
@@ -42,6 +42,6 @@ To do this in VS Code you can install the [YAML Extension](https://marketplace.v
 
 Use this method if you want to apply the schema to all YAML files in your project without modifying them. Open the IDE settings and navigate to `Languages & Frameworks` -> `Schemas and DTDs` -> `JSON Schema Mappings` and add a new schema using the "+" icon as shown below:
 
-![Goland Schema Mapping](.images/goland-json-schema.png)
+![Goland Schema Mapping](https://github.com/defenseunicorns/uds-cli/blob/main/docs/.images/goland-json-schema.png?raw=true)
 
 Don't forget to set the file path pattern for the JSON schema to apply to.

src/cmd/completion.go

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The UDS Authors
+
+// Package cmd contains the CLI commands for UDS.
+package cmd
+
+import (
+	"os"
+
+	"github.com/defenseunicorns/uds-cli/src/config/lang"
+	"github.com/spf13/cobra"
+)
+
+// We manually create the completion cmds because autogen'ing the docs includes Powershell completions,
+// which we don't support. Cobra doesn't provide a neat mechanism for excluding just Powershell so if we want
+// these completion cmds built into the CLI we have to create them manually
+var completionCmd = &cobra.Command{
+	Use:   "completion [command]",
+	Short: lang.CompletionCmdShort,
+	Long:  lang.CompletionCmdLong,
+}
+
+var noDesc = rootCmd.CompletionOptions.DisableDescriptions
+
+var bashCompletionCmd = &cobra.Command{
+	Use:                   "bash",
+	Short:                 lang.CompletionCmdShortBash,
+	DisableFlagsInUseLine: true,
+	Args:                  cobra.NoArgs,
+	Long: `Generate the autocompletion script for the bash shell.
+
+This script depends on the 'bash-completion' package.
+If it is not installed already, you can install it via your OS's package manager.
+
+To load completions in your current shell session:
+
+	source <(uds completion bash)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+	uds completion bash > /etc/bash_completion.d/uds
+
+#### macOS:
+
+	uds completion bash > $(brew --prefix)/etc/bash_completion.d/uds
+
+You will need to start a new shell for this setup to take effect.
+`,
+	RunE: func(cmd *cobra.Command, _ []string) error {
+		err := cmd.Root().GenBashCompletionV2(os.Stdout, !noDesc)
+		if err != nil {
+			return err
+		}
+		return nil
+	},
+}
+
+var zshCompletionCmd = &cobra.Command{
+	Use:   "zsh [flags]",
+	Short: lang.CompletionCmdShortZsh,
+	Args:  cobra.NoArgs,
+	Long: `Generate the autocompletion script for the zsh shell.
+
+If shell completion is not already enabled in your environment you will need
+to enable it.  You can execute the following once:
+
+	echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+To load completions in your current shell session:
+
+	source <(uds completion zsh)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+	uds completion zsh > "${fpath[1]}/_uds"
+
+#### macOS:
+
+	uds completion zsh > $(brew --prefix)/share/zsh/site-functions/_uds
+
+You will need to start a new shell for this setup to take effect.
+`,
+	RunE: func(cmd *cobra.Command, _ []string) error {
+		err := cmd.Root().GenZshCompletion(os.Stdout)
+		if err != nil {
+			return err
+		}
+		return nil
+	},
+}
+
+var fishCompletionCmd = &cobra.Command{
+	Use:   "fish [flags]",
+	Short: lang.CompletionCmdShortFish,
+	Args:  cobra.NoArgs,
+	Long: `Generate the autocompletion script for the fish shell.
+
+To load completions in your current shell session:
+
+	uds completion fish | source
+
+To load completions for every new session, execute once:
+
+	uds completion fish > ~/.config/fish/completions/uds.fish
+
+You will need to start a new shell for this setup to take effect.
+`,
+	RunE: func(cmd *cobra.Command, _ []string) error {
+		err := cmd.Root().GenFishCompletion(os.Stdout, !noDesc)
+		if err != nil {
+			return err
+		}
+		return nil
+	},
+}
+
+func init() {
+	initViper()
+	rootCmd.AddCommand(completionCmd)
+	completionCmd.AddCommand(bashCompletionCmd)
+	completionCmd.AddCommand(zshCompletionCmd)
+	completionCmd.AddCommand(fishCompletionCmd)
+
+	haveNoDescFlag := !rootCmd.CompletionOptions.DisableNoDescFlag && !rootCmd.CompletionOptions.DisableDescriptions
+	if haveNoDescFlag {
+		bashCompletionCmd.Flags().BoolVar(&noDesc, lang.CompletionNoDescFlagName, lang.CompletionNoDescFlagDefault, lang.CompletionNoDescFlagDesc)
+		fishCompletionCmd.Flags().BoolVar(&noDesc, lang.CompletionNoDescFlagName, lang.CompletionNoDescFlagDefault, lang.CompletionNoDescFlagDesc)
+		zshCompletionCmd.Flags().BoolVar(&noDesc, lang.CompletionNoDescFlagName, lang.CompletionNoDescFlagDefault, lang.CompletionNoDescFlagDesc)
+	}
+}

src/cmd/internal.go

@@ -46,7 +46,7 @@ var configTasksSchemaCmd = &cobra.Command{
 	Use:     "config-tasks-schema",
 	Aliases: []string{"c"},
 	Short:   lang.CmdInternalConfigSchemaShort,
-	Run: func(cmd *cobra.Command, input []string) {
+	Run: func(_ *cobra.Command, _ []string) {
 		runnerCLI.RootCmd().SetArgs([]string{"internal", "config-tasks-schema"})
 		runnerCLI.Execute()
 	},
@@ -104,9 +104,6 @@ type: docs
 			return err
 		}
 
-		// Remove the PowerShell completion documentation
-		os.Remove("./docs/command-reference/uds_completion_powershell.md")
-
 		message.Success(lang.CmdInternalGenerateCliDocsSuccess)
 		return nil
 	},

src/cmd/root.go

@@ -88,6 +88,9 @@ func init() {
 		}
 	}
 
+	// disable default completion command
+	rootCmd.CompletionOptions.DisableDefaultCmd = true
+
 	v.SetDefault(V_LOG_LEVEL, "info")
 	v.SetDefault(V_ARCHITECTURE, "")
 	v.SetDefault(V_NO_LOG_FILE, false)

src/config/lang/lang.go

@@ -17,6 +17,16 @@ const (
 	RootCmdErrInvalidLogLevel = "Invalid log level. Valid options are: warn, info, debug, trace."
 	RootCmdFlagArch           = "Architecture for UDS bundles and Zarf packages"
 
+	// completion
+	CompletionCmdShort          = "Generate the autocompletion script for the specified shell"
+	CompletionCmdLong           = "Generate the autocompletion script for uds for the specified shell.\nSee each sub-command's help for details on how to use the generated script.\n"
+	CompletionCmdShortBash      = "Generate the autocompletion script for bash"
+	CompletionCmdShortZsh       = "Generate the autocompletion script for zsh"
+	CompletionCmdShortFish      = "Generate the autocompletion script for fish"
+	CompletionNoDescFlagName    = "no-descriptions"
+	CompletionNoDescFlagDesc    = "disable completion descriptions"
+	CompletionNoDescFlagDefault = false
+
 	// logs
 	CmdBundleLogsShort = "View most recent UDS CLI logs"
 

src/test/e2e/completion_test.go

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The UDS Authors
+
+// Package test provides e2e tests for UDS.
+package test
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/defenseunicorns/uds-cli/src/config/lang"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCompletion(t *testing.T) {
+
+	t.Run("Test Completion", func(t *testing.T) {
+		cmd := strings.Split("completion", " ")
+		output, _, _ := e2e.UDS(cmd...)
+		require.Contains(t, output, lang.CompletionCmdLong)
+	})
+
+	t.Run("Test Bash Completion", func(t *testing.T) {
+		cmd := strings.Split("completion bash", " ")
+		output, _, _ := e2e.UDS(cmd...)
+		require.Contains(t, output, "bash completion V2 for uds")
+	})
+
+	t.Run("Test ZSH Completion", func(t *testing.T) {
+		cmd := strings.Split("completion zsh", " ")
+		output, _, _ := e2e.UDS(cmd...)
+		require.Contains(t, output, "zsh completion for uds")
+	})
+
+	t.Run("Test Fish Completion", func(t *testing.T) {
+		cmd := strings.Split("completion fish", " ")
+		output, _, _ := e2e.UDS(cmd...)
+		require.Contains(t, output, "fish completion for uds")
+	})
+}

tasks/tests.yaml

@@ -17,6 +17,11 @@ tasks:
     actions:
       - cmd: cd src/test/e2e && go test -failfast -v -timeout 30m bundle_test.go commands_test.go main_test.go
 
+  - name: completion
+    description: only run tests in completion_test.go
+    actions:
+      - cmd: cd src/test/e2e && go test -failfast -v -timeout 30m completion_test.go main_test.go
+
   - name: dev
     description: only run tests in dev.go
     actions: