docs: Add Cobra docs generator and CI

.github/workflows/docs.yml

@@ -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: Check docs are up to date
+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

@@ -315,7 +315,8 @@ debug = true
 debug-logs = true
 ```
 
-Run `./alloydb-auth-proxy --help` for more details.
+Run `./alloydb-auth-proxy --help` for more details. See the full documentation
+in [docs/cmd](docs/cmd).
 
 
 ## Running behind a Socks5 proxy

cmd/gendocs/gen_alloydb-proxy_docs.go

@@ -0,0 +1,50 @@
+// 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/alloydb-auth-proxy/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")
+
+	c := cmd.NewCommand()
+	c.Execute()
+	doc.GenMarkdownTree(c.Command, outDir)
+}