feat: adds doc auto generation for CLI commands (#140)

Signed-off-by: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com>

Author: ChrisJBurns

.gitattributes

@@ -0,0 +1,5 @@
+# This file is documented at https://git-scm.com/docs/gitattributes.
+# Linguist-specific attributes are documented at
+# https://github.com/github/linguist.
+
+docs/cli/thv*.md linguist-generated=true

.github/workflows/image-build-and-publish.yml

@@ -52,7 +52,7 @@ jobs:
       - name: Build and Push Image to GHCR
         run: |
           TAG=$(echo "${{ steps.version-string.outputs.tag }}" | sed 's/+/_/g')
-          KO_DOCKER_REPO=$BASE_REPO ko build --platform=linux/amd64,linux/arm64 --bare -t $TAG ./cmd/thv \
+          KO_DOCKER_REPO=$BASE_REPO ko build --platform=linux/amd64,linux/arm64 --bare -t $TAG ./cmd \
             --image-label=org.opencontainers.image.source=https://github.com/StacklokLabs/toolhive,org.opencontainers.image.title="toolhive",org.opencontainers.image.vendor=Stacklok
 
       - name: Sign Image with Cosign

.github/workflows/run-on-pr.yml

@@ -12,3 +12,6 @@ jobs:
   tests:
     name: Tests
     uses: ./.github/workflows/test.yml
+  docs:
+    name: Docs
+    uses: ./.github/workflows/verify-docgen.yml

.github/workflows/verify-docgen.yml

@@ -0,0 +1,16 @@
+name: Docgen
+
+on:
+  workflow_call:
+
+jobs:
+  docgen:
+    name: Verify Docgen
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+      - uses: actions/setup-go@0aaccfd150d50ccaeb58ebd88d36e91967a5f35b # v5
+        with:
+          go-version: '1.24.x'
+      - run: ./cmd/help/verify.sh

.goreleaser.yaml

@@ -22,7 +22,7 @@ builds:
     goarch:
       - amd64
       - arm64
-    main: ./cmd/thv
+    main: ./cmd
     binary: thv
 # This section defines the release format.
 archives:

Taskfile.yml

@@ -1,6 +1,12 @@
 version: '3'
 
 tasks:
+
+  docs:
+    desc: Generate the docs
+    cmds:
+      - go run cmd/help/main.go --dir docs/cli
+
   lint:
     desc: Run linting tools
     cmds:
@@ -37,7 +43,7 @@ tasks:
         sh: date -u +"%Y-%m-%dT%H:%M:%SZ"
     cmds:
       - mkdir -p bin
-      - go build -ldflags "-s -w -X github.com/StacklokLabs/toolhive/cmd/thv.Version={{.VERSION}} -X github.com/stacklok/toolhive/cmd/thv.Commit={{.COMMIT}} -X github.com/stacklok/toolhive/cmd/thv.BuildDate={{.BUILD_DATE}}" -o bin/thv ./cmd/thv
+      - go build -ldflags "-s -w -X github.com/StacklokLabs/toolhive/cmd/thv.Version={{.VERSION}} -X github.com/StacklokLabs/toolhive/cmd/thv.Commit={{.COMMIT}} -X github.com/StacklokLabs/toolhive/cmd/thv.BuildDate={{.BUILD_DATE}}" -o bin/thv ./cmd
 
   install:
     desc: Install the thv binary to GOPATH/bin
@@ -49,7 +55,7 @@ tasks:
       BUILD_DATE:
         sh: date -u +"%Y-%m-%dT%H:%M:%SZ"
     cmds:
-      - go install -ldflags "-s -w -X github.com/StacklokLabs/toolhive/cmd/thv.Version={{.VERSION}} -X github.com/stacklok/toolhive/cmd/thv.Commit={{.COMMIT}} -X github.com/stacklok/toolhive/cmd/thv.BuildDate={{.BUILD_DATE}}" -v ./cmd/thv
+      - go install -ldflags "-s -w -X github.com/StacklokLabs/toolhive/cmd/thv.Version={{.VERSION}} -X github.com/StacklokLabs/toolhive/cmd/thv.Commit={{.COMMIT}} -X github.com/StacklokLabs/toolhive/cmd/thv.BuildDate={{.BUILD_DATE}}" -v ./cmd
 
   all:
     desc: Run linting, tests, and build
@@ -62,13 +68,13 @@ tasks:
   build-image:
     desc: Build the image with ko
     cmds:
-      - ko build --platform linux/amd64,linux/arm64 --local ./cmd/thv
+      - ko build --platform linux/amd64,linux/arm64 --local ./cmd
 
   test-k8s-apply:
     desc: Builds the image, loads it into kind, and applies the Kubernetes manifests
     vars:
       IMAGE:
-        sh: ko build --platform linux/amd64 --local -B ./cmd/thv | tail -n 1
+        sh: ko build --platform linux/amd64 --local -B ./cmd | tail -n 1
     cmds:
       # gets the local kind kubeconfig
       - kind get kubeconfig > kconfig.yaml

cmd/help/main.go

@@ -0,0 +1,30 @@
+// Package main is the entry point for the ToolHive CLI Doc Generator.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+
+	cli "github.com/StacklokLabs/toolhive/cmd/thv"
+)
+
+func main() {
+	var dir string
+	root := &cobra.Command{
+		Use:          "gendoc",
+		Short:        "Generate ToolHive's help docs",
+		SilenceUsage: true,
+		Args:         cobra.NoArgs,
+		RunE: func(*cobra.Command, []string) error {
+			return doc.GenMarkdownTree(cli.NewRootCmd(), dir)
+		},
+	}
+	root.Flags().StringVarP(&dir, "dir", "d", "doc", "Path to directory in which to generate docs")
+	if err := root.Execute(); err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+}

cmd/help/verify.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -e
+
+# Verify that generated Markdown docs are up-to-date.
+tmpdir=$(mktemp -d)
+go run cmd/help/main.go --dir "$tmpdir"
+echo "###########################################"
+echo "If diffs are found, run: `task docs`"
+echo "###########################################"
+diff -Naur "$tmpdir" docs/cli/

cmd/main.go

@@ -0,0 +1,19 @@
+// Package main is the entry point for the ToolHive CLI.
+package main
+
+import (
+	"os"
+
+	cli "github.com/StacklokLabs/toolhive/cmd/thv"
+	"github.com/StacklokLabs/toolhive/pkg/logger"
+)
+
+func main() {
+	// Initialize the logger system
+	logger.Initialize()
+
+	if err := cli.NewRootCmd().Execute(); err != nil {
+		logger.Log.Error("%v, %v", os.Stderr, err)
+		os.Exit(1)
+	}
+}

cmd/thv/main.go renamed to cmd/thv/commands.go

@@ -1,17 +1,18 @@
-package main
+// Package cli provides the entry point for the toolhive command-line application.
+package cli
 
 import (
 	"fmt"
-	"os"
 
 	"github.com/spf13/cobra"
 
 	"github.com/StacklokLabs/toolhive/pkg/logger"
 )
 
 var rootCmd = &cobra.Command{
-	Use:   "thv",
-	Short: "ToolHive (thv) is a lightweight, secure, and fast manager for MCP servers",
+	Use:               "thv",
+	DisableAutoGenTag: true,
+	Short:             "ToolHive (thv) is a lightweight, secure, and fast manager for MCP servers",
 	Long: `ToolHive (thv) is a lightweight, secure, and fast manager for MCP (Model Context Protocol) servers.
 It is written in Go and has extensive test coverage—including input validation—to ensure reliability and security.
 
@@ -26,10 +27,8 @@ container-based isolation for running MCP servers.`,
 	},
 }
 
-func init() {
-	// Initialize the logger system
-	logger.Initialize()
-
+// NewRootCmd creates a new root command for the ToolHive CLI.
+func NewRootCmd() *cobra.Command {
 	// Add persistent flags
 	rootCmd.PersistentFlags().Bool("debug", false, "Enable debug mode")
 
@@ -43,11 +42,6 @@ func init() {
 	rootCmd.AddCommand(newVersionCmd())
 	rootCmd.AddCommand(newLogsCommand())
 	rootCmd.AddCommand(newSecretCommand())
-}
 
-func main() {
-	if err := rootCmd.Execute(); err != nil {
-		logger.Log.Error("%v, %v", os.Stderr, err)
-		os.Exit(1)
-	}
+	return rootCmd
 }