docs: Add Cobra docs generator and CI to ensure they remain up to date (

#2336)

Co-authored-by: Jack Wotherspoon <[email protected]>

.github/workflows/docs.yaml

@@ -0,0 +1,37 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: docs
+on:
+  pull_request:
+
+# Declare default permissions as read only.
+permissions: read-all
+
+jobs:
+  docs:
+    name: Check docs are up to date
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup Go
+        uses: actions/setup-go@41dfa10bad2bb2ae585af6ee5bb4d7d973ad74ed # v5.1.0
+        with:
+          go-version: "1.23"
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - name: Generate docs and fail if there are differences
+        run: |
+          go install ./cmd/gendocs
+          gendocs
+          git diff --exit-code

README.md

@@ -371,7 +371,8 @@ debug = true
 debug-logs = true
 ```
 
-Run `./cloud-sql-proxy --help` for more details.
+Run `./cloud-sql-proxy --help` for more details. See the full documentation
+in [docs/cmd](docs/cmd).
 
 ### Config environment variables
 

cmd/gendocs/gen_cloud-sql-proxy_docs.go

@@ -0,0 +1,51 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/GoogleCloudPlatform/cloud-sql-proxy/v2/cmd"
+	"github.com/spf13/cobra/doc"
+)
+
+func main() {
+	if len(os.Args) > 2 {
+		fmt.Fprintf(os.Stderr, "usage: %s [output directory]\n", os.Args[0])
+		os.Exit(1)
+	}
+
+	path := "docs/cmd"
+	if len(os.Args) == 2 {
+		path = os.Args[1]
+	}
+
+	outDir, err := filepath.Abs(path)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "failed to get output directory: %v\n", err)
+		os.Exit(1)
+	}
+
+	// Set environment variables used so the output is consistent,
+	// regardless of where we run.
+	os.Setenv("TMPDIR", "/tmp")
+
+	cloudSQLProxy := cmd.NewCommand()
+	cloudSQLProxy.Execute()
+	cloudSQLProxy.Command.DisableAutoGenTag = true
+	doc.GenMarkdownTree(cloudSQLProxy.Command, outDir)
+}

docs/cmd/cloud-sql-proxy_completion.md

@@ -0,0 +1,31 @@
+## cloud-sql-proxy completion
+
+Generate the autocompletion script for the specified shell
+
+### Synopsis
+
+Generate the autocompletion script for cloud-sql-proxy 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
+
+```
+      --http-address string   Address for Prometheus and health check server (default "localhost")
+      --http-port string      Port for Prometheus and health check server (default "9090")
+```
+
+### SEE ALSO
+
+* [cloud-sql-proxy](cloud-sql-proxy.md)	 - cloud-sql-proxy authorizes and encrypts connections to Cloud SQL.
+* [cloud-sql-proxy completion bash](cloud-sql-proxy_completion_bash.md)	 - Generate the autocompletion script for bash
+* [cloud-sql-proxy completion fish](cloud-sql-proxy_completion_fish.md)	 - Generate the autocompletion script for fish
+* [cloud-sql-proxy completion powershell](cloud-sql-proxy_completion_powershell.md)	 - Generate the autocompletion script for powershell
+* [cloud-sql-proxy completion zsh](cloud-sql-proxy_completion_zsh.md)	 - Generate the autocompletion script for zsh
+

docs/cmd/cloud-sql-proxy_completion_bash.md

@@ -0,0 +1,50 @@
+## cloud-sql-proxy 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 <(cloud-sql-proxy completion bash)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+	cloud-sql-proxy completion bash > /etc/bash_completion.d/cloud-sql-proxy
+
+#### macOS:
+
+	cloud-sql-proxy completion bash > $(brew --prefix)/etc/bash_completion.d/cloud-sql-proxy
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+cloud-sql-proxy completion bash
+```
+
+### Options
+
+```
+  -h, --help              help for bash
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+      --http-address string   Address for Prometheus and health check server (default "localhost")
+      --http-port string      Port for Prometheus and health check server (default "9090")
+```
+
+### SEE ALSO
+
+* [cloud-sql-proxy completion](cloud-sql-proxy_completion.md)	 - Generate the autocompletion script for the specified shell
+

docs/cmd/cloud-sql-proxy_completion_fish.md

@@ -0,0 +1,41 @@
+## cloud-sql-proxy 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:
+
+	cloud-sql-proxy completion fish | source
+
+To load completions for every new session, execute once:
+
+	cloud-sql-proxy completion fish > ~/.config/fish/completions/cloud-sql-proxy.fish
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+cloud-sql-proxy completion fish [flags]
+```
+
+### Options
+
+```
+  -h, --help              help for fish
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+      --http-address string   Address for Prometheus and health check server (default "localhost")
+      --http-port string      Port for Prometheus and health check server (default "9090")
+```
+
+### SEE ALSO
+
+* [cloud-sql-proxy completion](cloud-sql-proxy_completion.md)	 - Generate the autocompletion script for the specified shell
+

docs/cmd/cloud-sql-proxy_completion_powershell.md

@@ -0,0 +1,38 @@
+## cloud-sql-proxy completion powershell
+
+Generate the autocompletion script for powershell
+
+### Synopsis
+
+Generate the autocompletion script for powershell.
+
+To load completions in your current shell session:
+
+	cloud-sql-proxy completion powershell | Out-String | Invoke-Expression
+
+To load completions for every new session, add the output of the above command
+to your powershell profile.
+
+
+```
+cloud-sql-proxy completion powershell [flags]
+```
+
+### Options
+
+```
+  -h, --help              help for powershell
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+      --http-address string   Address for Prometheus and health check server (default "localhost")
+      --http-port string      Port for Prometheus and health check server (default "9090")
+```
+
+### SEE ALSO
+
+* [cloud-sql-proxy completion](cloud-sql-proxy_completion.md)	 - Generate the autocompletion script for the specified shell
+

docs/cmd/cloud-sql-proxy_completion_zsh.md

@@ -0,0 +1,52 @@
+## cloud-sql-proxy 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 <(cloud-sql-proxy completion zsh)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+	cloud-sql-proxy completion zsh > "${fpath[1]}/_cloud-sql-proxy"
+
+#### macOS:
+
+	cloud-sql-proxy completion zsh > $(brew --prefix)/share/zsh/site-functions/_cloud-sql-proxy
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+cloud-sql-proxy completion zsh [flags]
+```
+
+### Options
+
+```
+  -h, --help              help for zsh
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+      --http-address string   Address for Prometheus and health check server (default "localhost")
+      --http-port string      Port for Prometheus and health check server (default "9090")
+```
+
+### SEE ALSO
+
+* [cloud-sql-proxy completion](cloud-sql-proxy_completion.md)	 - Generate the autocompletion script for the specified shell
+

docs/cmd/cloud-sql-proxy_wait.md

@@ -0,0 +1,66 @@
+## cloud-sql-proxy wait
+
+Wait for another Proxy process to start
+
+### Synopsis
+
+
+Waiting for Proxy Startup
+
+  Sometimes it is necessary to wait for the Proxy to start.
+
+  To help ensure the Proxy is up and ready, the Proxy includes a wait
+  subcommand with an optional --max flag to set the maximum time to wait.
+  The wait command uses a separate Proxy's startup endpoint to determine
+  if the other Proxy process is ready.
+
+  Invoke the wait command, like this:
+
+  # waits for another Proxy process' startup endpoint to respond
+  ./cloud-sql-proxy wait
+
+Configuration
+
+  By default, the Proxy will wait up to the maximum time for the startup
+  endpoint to respond. The wait command requires that the Proxy be started in
+  another process with the HTTP health check enabled. If an alternate health
+  check port or address is used, as in:
+
+  ./cloud-sql-proxy <INSTANCE_CONNECTION_NAME> \
+    --http-address 0.0.0.0 \
+    --http-port 9191
+
+  Then the wait command must also be told to use the same custom values:
+
+  ./cloud-sql-proxy wait \
+    --http-address 0.0.0.0 \
+    --http-port 9191
+
+  By default the wait command will wait 30 seconds. To alter this value,
+  use:
+
+  ./cloud-sql-proxy wait --max 10s
+
+
+```
+cloud-sql-proxy wait [flags]
+```
+
+### Options
+
+```
+  -h, --help           help for wait
+  -m, --max duration   maximum amount of time to wait for startup (default 30s)
+```
+
+### Options inherited from parent commands
+
+```
+      --http-address string   Address for Prometheus and health check server (default "localhost")
+      --http-port string      Port for Prometheus and health check server (default "9090")
+```
+
+### SEE ALSO
+
+* [cloud-sql-proxy](cloud-sql-proxy.md)	 - cloud-sql-proxy authorizes and encrypts connections to Cloud SQL.
+

go.mod

@@ -34,6 +34,7 @@ require (
 	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/census-instrumentation/opencensus-proto v0.4.1 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.4 // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/fsnotify/fsnotify v1.7.0 // indirect
 	github.com/go-kit/log v0.2.1 // indirect
@@ -64,6 +65,7 @@ require (
 	github.com/prometheus/procfs v0.8.0 // indirect
 	github.com/prometheus/prometheus v0.35.0 // indirect
 	github.com/prometheus/statsd_exporter v0.22.7 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/sagikazarmark/locafero v0.4.0 // indirect
 	github.com/sagikazarmark/slog-shim v0.1.0 // indirect
 	github.com/sourcegraph/conc v0.3.0 // indirect