From 507e96221627f578dea2456fae37d64923981a9e Mon Sep 17 00:00:00 2001 From: Charles Treatman Date: Fri, 3 Oct 2025 12:33:32 -0500 Subject: [PATCH 1/3] feat: add subcommand for generating docs --- .github/workflows/validate_docs.yaml | 41 ++++++++++++++++++++++++++++ Makefile | 15 ++++++++-- cmd/docs.go | 25 +++++++++++++++++ go.mod | 2 ++ go.sum | 2 ++ 5 files changed, 83 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/validate_docs.yaml create mode 100644 cmd/docs.go diff --git a/.github/workflows/validate_docs.yaml b/.github/workflows/validate_docs.yaml new file mode 100644 index 0000000..00e8011 --- /dev/null +++ b/.github/workflows/validate_docs.yaml @@ -0,0 +1,41 @@ +on: + pull_request: + +permissions: + contents: read + pull-requests: write + +jobs: + validate_docs: + name: Validate CLI Docs + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4 + with: + fetch-depth: 1 + + - name: Set up Go + uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5 + with: + go-version-file: go.mod + + - name: Build CLI docs + run: make docs + + - name: Detect Uncommitted Docs + id: validate_docs + run: make docs-check + + - uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2.9.4 + if: always() && (steps.validate_docs.outcome == 'failure') + with: + header: pr-docs-error + message: | + Uncommitted changes were detected in the `docs/` directory. Please run `make docs` and commit the changes to your branch. + + # Delete a previous comment when the docs have been updated + - if: ${{ steps.validate_docs.outcome == 'success' }} + uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2.9.4 + with: + header: pr-docs-error + delete: true \ No newline at end of file diff --git a/Makefile b/Makefile index 3e475ef..6fb4f7a 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ +.PHONY: lint fix build docs docs-check BINARY=equinix - GOLANGCI_LINT_VERSION=v2.3.0 GOLANGCI_LINT=go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@${GOLANGCI_LINT_VERSION} @@ -11,4 +11,15 @@ fix: $(GOLANGCI_LINT) run -v --fix build: - go build $(LDFLAGS) -o bin/$(BINARY) main.go \ No newline at end of file + go build $(LDFLAGS) -o bin/$(BINARY) main.go + +docs: + rm -rf docs/ + mkdir -p docs + go run main.go docs ./docs + +docs-check: docs + if git status --porcelain | grep docs; then \ + echo "Uncommitted changes detected. Run 'make docs' and commit changes."; \ + exit 1; \ + fi \ No newline at end of file diff --git a/cmd/docs.go b/cmd/docs.go new file mode 100644 index 0000000..76b8a7e --- /dev/null +++ b/cmd/docs.go @@ -0,0 +1,25 @@ +package cmd + +import ( + "github.com/spf13/cobra" + "github.com/spf13/cobra/doc" +) + +var docsCmd = &cobra.Command{ + Use: `docs `, + Short: "Generate markdown documentation for this CLI", + Long: "Generates markdown documentation for this CLI in the specified directory. Each command gets a markdown file.", + Example: ` # Generate documentation in the ./docs directory: + equinix docs ./docs`, + + DisableFlagsInUseLine: true, + Args: cobra.MatchAll(cobra.ExactArgs(1), cobra.OnlyValidArgs), + RunE: func(cmd *cobra.Command, args []string) error { + dest := args[0] + return doc.GenMarkdownTree(cmd.Parent(), dest) + }, +} + +func init() { + rootCmd.AddCommand(docsCmd) +} diff --git a/go.mod b/go.mod index e1f79ae..b478fde 100644 --- a/go.mod +++ b/go.mod @@ -10,10 +10,12 @@ require ( ) require ( + github.com/cpuguy83/go-md2man/v2 v2.0.6 // indirect github.com/fsnotify/fsnotify v1.8.0 // indirect github.com/go-viper/mapstructure/v2 v2.2.1 // indirect github.com/inconshreveable/mousetrap v1.1.0 // indirect github.com/pelletier/go-toml/v2 v2.2.3 // indirect + github.com/russross/blackfriday/v2 v2.1.0 // indirect github.com/sagikazarmark/locafero v0.7.0 // indirect github.com/sourcegraph/conc v0.3.0 // indirect github.com/spf13/afero v1.12.0 // indirect diff --git a/go.sum b/go.sum index d993bd5..a15e322 100644 --- a/go.sum +++ b/go.sum @@ -1,3 +1,4 @@ +github.com/cpuguy83/go-md2man/v2 v2.0.6 h1:XJtiaUW6dEEqVuZiMTn1ldk455QWwEIsMIJlo5vtkx0= github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g= github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= @@ -24,6 +25,7 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8= github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs= +github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk= github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= github.com/sagikazarmark/locafero v0.7.0 h1:5MqpDsTGNDhY8sGp0Aowyf0qKsPrhewaLSsFaodPcyo= github.com/sagikazarmark/locafero v0.7.0/go.mod h1:2za3Cg5rMaTMoG/2Ulr9AwtFaIppKXTRYnozin4aB5k= From 959d17d1ab5af886e23d47b71d985f8a69f60b30 Mon Sep 17 00:00:00 2001 From: Charles Treatman Date: Mon, 6 Oct 2025 11:46:36 -0500 Subject: [PATCH 2/3] add generated docs --- docs/equinix.md | 22 ++++++++++++ docs/equinix_api.md | 33 +++++++++++++++++ docs/equinix_completion.md | 31 ++++++++++++++++ docs/equinix_completion_bash.md | 50 ++++++++++++++++++++++++++ docs/equinix_completion_fish.md | 41 +++++++++++++++++++++ docs/equinix_completion_powershell.md | 38 ++++++++++++++++++++ docs/equinix_completion_zsh.md | 52 +++++++++++++++++++++++++++ docs/equinix_docs.md | 36 +++++++++++++++++++ 8 files changed, 303 insertions(+) create mode 100644 docs/equinix.md create mode 100644 docs/equinix_api.md create mode 100644 docs/equinix_completion.md create mode 100644 docs/equinix_completion_bash.md create mode 100644 docs/equinix_completion_fish.md create mode 100644 docs/equinix_completion_powershell.md create mode 100644 docs/equinix_completion_zsh.md create mode 100644 docs/equinix_docs.md diff --git a/docs/equinix.md b/docs/equinix.md new file mode 100644 index 0000000..a86226c --- /dev/null +++ b/docs/equinix.md @@ -0,0 +1,22 @@ +## equinix + +Equinix CLI + +### Synopsis + +Command-line interface for Equinix APIs + +### Options + +``` + --config string config file (default is $HOME/.cli.yaml) + -h, --help help for equinix +``` + +### SEE ALSO + +* [equinix api](equinix_api.md) - Make a raw API request to the given Equinix API path +* [equinix completion](equinix_completion.md) - Generate the autocompletion script for the specified shell +* [equinix docs](equinix_docs.md) - Generate markdown documentation for this CLI + +###### Auto generated by spf13/cobra on 6-Oct-2025 diff --git a/docs/equinix_api.md b/docs/equinix_api.md new file mode 100644 index 0000000..70d37a3 --- /dev/null +++ b/docs/equinix_api.md @@ -0,0 +1,33 @@ +## equinix api + +Make a raw API request to the given Equinix API path + +### Synopsis + +Make a raw authenticated request to the Equinix API using your configured credentials. + +``` +equinix api [url-path] [flags] +``` + +### Options + +``` + -d, --data string Data to send with POST/PUT requests + -f, --format string Format to use for output (json or yaml) (default "json") + -h, --help help for api + -X, --method string HTTP method to use (default "GET") + --portal Use Equinix Portal API (cookie auth) +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.cli.yaml) +``` + +### SEE ALSO + +* [equinix](equinix.md) - Equinix CLI + +###### Auto generated by spf13/cobra on 6-Oct-2025 diff --git a/docs/equinix_completion.md b/docs/equinix_completion.md new file mode 100644 index 0000000..2f8ce0f --- /dev/null +++ b/docs/equinix_completion.md @@ -0,0 +1,31 @@ +## equinix completion + +Generate the autocompletion script for the specified shell + +### Synopsis + +Generate the autocompletion script for equinix 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 + +``` + --config string config file (default is $HOME/.cli.yaml) +``` + +### SEE ALSO + +* [equinix](equinix.md) - Equinix CLI +* [equinix completion bash](equinix_completion_bash.md) - Generate the autocompletion script for bash +* [equinix completion fish](equinix_completion_fish.md) - Generate the autocompletion script for fish +* [equinix completion powershell](equinix_completion_powershell.md) - Generate the autocompletion script for powershell +* [equinix completion zsh](equinix_completion_zsh.md) - Generate the autocompletion script for zsh + +###### Auto generated by spf13/cobra on 6-Oct-2025 diff --git a/docs/equinix_completion_bash.md b/docs/equinix_completion_bash.md new file mode 100644 index 0000000..04ae88e --- /dev/null +++ b/docs/equinix_completion_bash.md @@ -0,0 +1,50 @@ +## equinix 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 <(equinix completion bash) + +To load completions for every new session, execute once: + +#### Linux: + + equinix completion bash > /etc/bash_completion.d/equinix + +#### macOS: + + equinix completion bash > $(brew --prefix)/etc/bash_completion.d/equinix + +You will need to start a new shell for this setup to take effect. + + +``` +equinix completion bash +``` + +### Options + +``` + -h, --help help for bash + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.cli.yaml) +``` + +### SEE ALSO + +* [equinix completion](equinix_completion.md) - Generate the autocompletion script for the specified shell + +###### Auto generated by spf13/cobra on 6-Oct-2025 diff --git a/docs/equinix_completion_fish.md b/docs/equinix_completion_fish.md new file mode 100644 index 0000000..2980387 --- /dev/null +++ b/docs/equinix_completion_fish.md @@ -0,0 +1,41 @@ +## equinix 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: + + equinix completion fish | source + +To load completions for every new session, execute once: + + equinix completion fish > ~/.config/fish/completions/equinix.fish + +You will need to start a new shell for this setup to take effect. + + +``` +equinix completion fish [flags] +``` + +### Options + +``` + -h, --help help for fish + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.cli.yaml) +``` + +### SEE ALSO + +* [equinix completion](equinix_completion.md) - Generate the autocompletion script for the specified shell + +###### Auto generated by spf13/cobra on 6-Oct-2025 diff --git a/docs/equinix_completion_powershell.md b/docs/equinix_completion_powershell.md new file mode 100644 index 0000000..f5b111d --- /dev/null +++ b/docs/equinix_completion_powershell.md @@ -0,0 +1,38 @@ +## equinix completion powershell + +Generate the autocompletion script for powershell + +### Synopsis + +Generate the autocompletion script for powershell. + +To load completions in your current shell session: + + equinix completion powershell | Out-String | Invoke-Expression + +To load completions for every new session, add the output of the above command +to your powershell profile. + + +``` +equinix completion powershell [flags] +``` + +### Options + +``` + -h, --help help for powershell + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.cli.yaml) +``` + +### SEE ALSO + +* [equinix completion](equinix_completion.md) - Generate the autocompletion script for the specified shell + +###### Auto generated by spf13/cobra on 6-Oct-2025 diff --git a/docs/equinix_completion_zsh.md b/docs/equinix_completion_zsh.md new file mode 100644 index 0000000..73d2364 --- /dev/null +++ b/docs/equinix_completion_zsh.md @@ -0,0 +1,52 @@ +## equinix completion zsh + +Generate the autocompletion script for zsh + +### Synopsis + +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 <(equinix completion zsh) + +To load completions for every new session, execute once: + +#### Linux: + + equinix completion zsh > "${fpath[1]}/_equinix" + +#### macOS: + + equinix completion zsh > $(brew --prefix)/share/zsh/site-functions/_equinix + +You will need to start a new shell for this setup to take effect. + + +``` +equinix completion zsh [flags] +``` + +### Options + +``` + -h, --help help for zsh + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.cli.yaml) +``` + +### SEE ALSO + +* [equinix completion](equinix_completion.md) - Generate the autocompletion script for the specified shell + +###### Auto generated by spf13/cobra on 6-Oct-2025 diff --git a/docs/equinix_docs.md b/docs/equinix_docs.md new file mode 100644 index 0000000..6ee71c0 --- /dev/null +++ b/docs/equinix_docs.md @@ -0,0 +1,36 @@ +## equinix docs + +Generate markdown documentation for this CLI + +### Synopsis + +Generates markdown documentation for this CLI in the specified directory. Each command gets a markdown file. + +``` +equinix docs +``` + +### Examples + +``` + # Generate documentation in the ./docs directory: + equinix docs ./docs +``` + +### Options + +``` + -h, --help help for docs +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.cli.yaml) +``` + +### SEE ALSO + +* [equinix](equinix.md) - Equinix CLI + +###### Auto generated by spf13/cobra on 6-Oct-2025 From 31cfdab8ddfc7b0dc83e6b00d5eb1197d1ec6ee3 Mon Sep 17 00:00:00 2001 From: Charles Treatman Date: Mon, 6 Oct 2025 11:49:58 -0500 Subject: [PATCH 3/3] link to generated docs from README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 99f50be..da23e94 100644 --- a/README.md +++ b/README.md @@ -8,4 +8,4 @@ TODO ## Usage -TODO \ No newline at end of file +The full CLI documentation can be found [in the docs directory](docs/equinix.md). \ No newline at end of file