feat: now the documentation for the pizza-cli can be generated via pizza docs (#143)

* feat: now the documentation for the pizza-cli can be generated via pizza docs

* test: added some test for the docs command

* disabled auto generation of Cobra tail end in markdown

Co-authored-by: John McBride <john@opensauced.pizza>

* added docs/ to gitignore

* now docs are generated from the root command

* now all autogen tagging is disabled for doc generation

* docs command now hidden

* refactored directory creation out into functions

* simplified absolute filepath generation

Co-authored-by: John McBride <john@opensauced.pizza>

* docs: added CLI docs

* some cleanup

---------

Co-authored-by: John McBride <john@opensauced.pizza>

Author: nickytonline

cmd/docs/docs.go

@@ -0,0 +1,78 @@
+package docs
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+type Options struct {
+	Path string
+}
+
+const DefaultPath = "./docs"
+
+func GetDocsPath(path string) (string, error) {
+	if path == "" {
+		fmt.Printf("No path was provided. Using default path: %s\n", DefaultPath)
+		path = DefaultPath
+	}
+
+	absPath, err := filepath.Abs(path)
+
+	if err != nil {
+		return "", fmt.Errorf("error resolving absolute path: %w", err)
+	}
+
+	_, err = os.Stat(absPath)
+
+	if os.IsNotExist(err) {
+		fmt.Printf("The directory %s does not exist. Creating it...\n", absPath)
+		if err := os.MkdirAll(absPath, os.ModePerm); err != nil {
+			return "", fmt.Errorf("error creating directory %s: %w", absPath, err)
+		}
+	} else if err != nil {
+		return "", fmt.Errorf("error checking directory %s: %w", absPath, err)
+	}
+
+	return absPath, nil
+}
+
+func GenerateDocumentation(rootCmd *cobra.Command, path string) error {
+	fmt.Printf("Generating documentation in %s...\n", path)
+	err := doc.GenMarkdownTree(rootCmd, path)
+
+	if err != nil {
+		return err
+	}
+
+	fmt.Printf("Finished generating documentation in %s\n", path)
+
+	return nil
+}
+
+func NewDocsCommand() *cobra.Command {
+	return &cobra.Command{
+		Use:   "docs [path]",
+		Short: "Generates the documentation for the CLI",
+		Args:  cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cmd.Parent().Root().DisableAutoGenTag = true
+
+			var path string
+			if len(args) > 0 {
+				path = args[0]
+			}
+
+			resolvedPath, err := GetDocsPath(path)
+			if err != nil {
+				return err
+			}
+
+			return GenerateDocumentation(cmd.Parent().Root(), resolvedPath)
+		},
+	}
+}

cmd/docs/docs_test.go

@@ -0,0 +1,82 @@
+package docs
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestGetDocsPath(t *testing.T) {
+	t.Parallel()
+
+	t.Run("No path provided", func(t *testing.T) {
+		t.Parallel()
+		actual, err := GetDocsPath("")
+
+		if err != nil {
+			t.Errorf("GetDocsPath() error = %v, wantErr false", err)
+			return
+		}
+
+		expected, _ := filepath.Abs(DefaultPath)
+		if actual != expected {
+			t.Errorf("GetDocsPath() = %v, want %v", actual, expected)
+		}
+	})
+
+	t.Run("With path provided", func(t *testing.T) {
+		t.Parallel()
+		inputPath := filepath.Join(os.TempDir(), "docs")
+		actual, err := GetDocsPath(inputPath)
+
+		if err != nil {
+			t.Errorf("GetDocsPath() error = %v, wantErr false", err)
+			return
+		}
+
+		expected, _ := filepath.Abs(inputPath)
+		if actual != expected {
+			t.Errorf("GetDocsPath() = %v, want %v", actual, expected)
+		}
+
+		if _, err := os.Stat(actual); os.IsNotExist(err) {
+			t.Errorf("GetDocsPath() failed to create directory %s", actual)
+		}
+	})
+
+	t.Run("Invalid path", func(t *testing.T) {
+		t.Parallel()
+		invalidPath := string([]byte{0})
+
+		_, err := GetDocsPath(invalidPath)
+
+		if err == nil {
+			t.Errorf("GetDocsPath() error = nil, wantErr true")
+		}
+	})
+}
+
+func TestGetDocsPath_ExistingDirectory(t *testing.T) {
+	t.Parallel()
+
+	tempDir, err := os.MkdirTemp("", "docs_test_existing")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+
+	actual, err := GetDocsPath(tempDir)
+
+	if err != nil {
+		t.Errorf("GetDocsPath() error = %v, wantErr false", err)
+		return
+	}
+
+	expected, _ := filepath.Abs(tempDir)
+	if actual != expected {
+		t.Errorf("GetDocsPath() = %v, want %v", actual, expected)
+	}
+
+	if _, err := os.Stat(actual); os.IsNotExist(err) {
+		t.Errorf("GetDocsPath() failed to recognize existing directory %s", actual)
+	}
+}

cmd/root/root.go

@@ -7,6 +7,7 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/open-sauced/pizza-cli/cmd/auth"
+	"github.com/open-sauced/pizza-cli/cmd/docs"
 	"github.com/open-sauced/pizza-cli/cmd/generate"
 	"github.com/open-sauced/pizza-cli/cmd/insights"
 	"github.com/open-sauced/pizza-cli/cmd/version"
@@ -44,6 +45,11 @@ func NewRootCommand() (*cobra.Command, error) {
 	cmd.AddCommand(insights.NewInsightsCommand())
 	cmd.AddCommand(version.NewVersionCommand())
 
+	// The docs command is hidden as it's only used by the pizza-cli maintainers
+	docsCmd := docs.NewDocsCommand()
+	docsCmd.Hidden = true
+	cmd.AddCommand(docsCmd)
+
 	err := cmd.PersistentFlags().MarkHidden(constants.FlagNameEndpoint)
 	if err != nil {
 		return nil, fmt.Errorf("error marking %s as hidden: %w", constants.FlagNameEndpoint, err)

docs/pizza.md

@@ -0,0 +1,30 @@
+## pizza
+
+OpenSauced CLI
+
+### Synopsis
+
+A command line utility for insights, metrics, and all things OpenSauced
+
+```
+pizza <command> <subcommand> [flags]
+```
+
+### Options
+
+```
+  -c, --config string       The saucectl config (default "~/.sauced.yaml")
+      --disable-telemetry   Disable sending telemetry data to OpenSauced
+  -h, --help                help for pizza
+  -l, --log-level string    The logging level. Options: error, warn, info, debug (default "info")
+      --tty-disable         Disable log stylization. Suitable for CI/CD and automation
+```
+
+### SEE ALSO
+
+* [pizza completion](pizza_completion.md)	 - Generate the autocompletion script for the specified shell
+* [pizza generate](pizza_generate.md)	 - Generates something
+* [pizza insights](pizza_insights.md)	 - Gather insights about git contributors, repositories, users and pull requests
+* [pizza login](pizza_login.md)	 - Log into the CLI via GitHub
+* [pizza version](pizza_version.md)	 - Displays the build version of the CLI
+

docs/pizza_completion.md

@@ -0,0 +1,33 @@
+## pizza completion
+
+Generate the autocompletion script for the specified shell
+
+### Synopsis
+
+Generate the autocompletion script for pizza for the specified shell.
+See each sub-command's help for details on how to use the generated script.
+
+
+### Options
+
+```
+  -h, --help   help for completion
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string       The saucectl config (default "~/.sauced.yaml")
+      --disable-telemetry   Disable sending telemetry data to OpenSauced
+  -l, --log-level string    The logging level. Options: error, warn, info, debug (default "info")
+      --tty-disable         Disable log stylization. Suitable for CI/CD and automation
+```
+
+### SEE ALSO
+
+* [pizza](pizza.md)	 - OpenSauced CLI
+* [pizza completion bash](pizza_completion_bash.md)	 - Generate the autocompletion script for bash
+* [pizza completion fish](pizza_completion_fish.md)	 - Generate the autocompletion script for fish
+* [pizza completion powershell](pizza_completion_powershell.md)	 - Generate the autocompletion script for powershell
+* [pizza completion zsh](pizza_completion_zsh.md)	 - Generate the autocompletion script for zsh
+

docs/pizza_completion_bash.md

@@ -0,0 +1,52 @@
+## pizza completion bash
+
+Generate the autocompletion script for bash
+
+### Synopsis
+
+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 <(pizza completion bash)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+	pizza completion bash > /etc/bash_completion.d/pizza
+
+#### macOS:
+
+	pizza completion bash > $(brew --prefix)/etc/bash_completion.d/pizza
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+pizza completion bash
+```
+
+### Options
+
+```
+  -h, --help              help for bash
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string       The saucectl config (default "~/.sauced.yaml")
+      --disable-telemetry   Disable sending telemetry data to OpenSauced
+  -l, --log-level string    The logging level. Options: error, warn, info, debug (default "info")
+      --tty-disable         Disable log stylization. Suitable for CI/CD and automation
+```
+
+### SEE ALSO
+
+* [pizza completion](pizza_completion.md)	 - Generate the autocompletion script for the specified shell
+

docs/pizza_completion_fish.md

@@ -0,0 +1,43 @@
+## pizza completion fish
+
+Generate the autocompletion script for fish
+
+### Synopsis
+
+Generate the autocompletion script for the fish shell.
+
+To load completions in your current shell session:
+
+	pizza completion fish | source
+
+To load completions for every new session, execute once:
+
+	pizza completion fish > ~/.config/fish/completions/pizza.fish
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+pizza completion fish [flags]
+```
+
+### Options
+
+```
+  -h, --help              help for fish
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string       The saucectl config (default "~/.sauced.yaml")
+      --disable-telemetry   Disable sending telemetry data to OpenSauced
+  -l, --log-level string    The logging level. Options: error, warn, info, debug (default "info")
+      --tty-disable         Disable log stylization. Suitable for CI/CD and automation
+```
+
+### SEE ALSO
+
+* [pizza completion](pizza_completion.md)	 - Generate the autocompletion script for the specified shell
+

docs/pizza_completion_powershell.md

@@ -0,0 +1,40 @@
+## pizza completion powershell
+
+Generate the autocompletion script for powershell
+
+### Synopsis
+
+Generate the autocompletion script for powershell.
+
+To load completions in your current shell session:
+
+	pizza completion powershell | Out-String | Invoke-Expression
+
+To load completions for every new session, add the output of the above command
+to your powershell profile.
+
+
+```
+pizza completion powershell [flags]
+```
+
+### Options
+
+```
+  -h, --help              help for powershell
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string       The saucectl config (default "~/.sauced.yaml")
+      --disable-telemetry   Disable sending telemetry data to OpenSauced
+  -l, --log-level string    The logging level. Options: error, warn, info, debug (default "info")
+      --tty-disable         Disable log stylization. Suitable for CI/CD and automation
+```
+
+### SEE ALSO
+
+* [pizza completion](pizza_completion.md)	 - Generate the autocompletion script for the specified shell
+