feat(docs): improve markdown doc generation command (#493)

reubeno · web-flow · commit 850bb4c1596e · 2026-03-03T10:37:50.000-08:00
Enhance the 'azldev docs markdown' command:
- Add --include-hidden flag to generate docs for hidden (advanced) commands
- Use GenMarkdownTreeCustom for proper cross-linking between pages
- Add auto-generated file header to prevent hand-editing
- Strip dynamic version string so docs don't churn on every build
- Clean stale .md files before regeneration
diff --git a/internal/app/azldev/cmds/docs/markdown.go b/internal/app/azldev/cmds/docs/markdown.go
@@ -5,16 +5,19 @@ package docs
 
 import (
 	"fmt"
+	"regexp"
 
 	"github.com/gim-home/azldev-preview/internal/app/azldev"
+	"github.com/gim-home/azldev-preview/internal/global/opctx"
 	"github.com/gim-home/azldev-preview/internal/utils/fileutils"
-	"github.com/spf13/afero"
 	"github.com/spf13/cobra"
 	"github.com/spf13/cobra/doc"
 )
 
 type GenerateMarkdownOptions struct {
-	OutputDir string
+	OutputDir     string
+	IncludeHidden bool
+	Force         bool
 }
 
 // Called once when the app is initialized; registers any commands or callbacks with the app.
@@ -29,12 +32,30 @@ func newMarkdownCmd() *cobra.Command {
 		Use:     "markdown",
 		Aliases: []string{"md"},
 		Short:   "Generates Markdown (.md) docs for this tool",
-		RunE: func(cmd *cobra.Command, args []string) error {
-			return GenerateMarkdownDocs(cmd.Root(), &options)
-		},
+		Long: `Generate Markdown reference documentation for all azldev CLI commands.
+
+Produces one .md file per command in the output directory. These files are
+auto-generated and should not be hand-edited; update the Cobra command
+definitions in Go source code instead, then re-run this command.`,
+		Example: `  # Generate docs into the user guide
+  azldev docs markdown -o docs/user/reference/cli/
+
+  # Include hidden (advanced) commands
+  azldev docs markdown -o docs/user/reference/cli/ --include-hidden
+
+  # Overwrite an existing non-empty output directory
+  azldev docs markdown -o docs/user/reference/cli/ -f`,
 	}
 
+	cmd.RunE = azldev.RunFuncWithoutRequiredConfig(
+		func(env *azldev.Env) (interface{}, error) {
+			return nil, GenerateMarkdownDocs(env.FS(), cmd.Root(), &options)
+		})
+
 	cmd.Flags().StringVarP(&options.OutputDir, "output-dir", "o", "", "directory markdown files will be written to")
+	cmd.Flags().BoolVarP(&options.Force, "force", "f", false,
+		"delete and recreate the output directory if it already exists")
+	cmd.Flags().BoolVar(&options.IncludeHidden, "include-hidden", false, "include hidden commands in the generated docs")
 
 	// NOTE: we ignore errors because we don't expect that they could fail at runtime, and because this function
 	// is expected to be infallible.
@@ -46,17 +67,107 @@ func newMarkdownCmd() *cobra.Command {
 	return cmd
 }
 
-// Generates markdown documentation for the given command tree.
-func GenerateMarkdownDocs(rootCmd *cobra.Command, options *GenerateMarkdownOptions) error {
-	// Make sure the directory exists.
-	err := fileutils.MkdirAll(afero.NewOsFs(), options.OutputDir)
+const generatedFileHeader = `<!--- DO NOT EDIT: auto-generated by "azldev docs markdown" -->` + "\n\n"
+
+// filePrepender returns a function that prepends the auto-generated header to each generated doc file.
+func filePrepender(_ string) string {
+	return generatedFileHeader
+}
+
+// linkHandler converts cobra doc filenames to relative markdown file links.
+// Cobra passes in filenames like "azldev_component.md"; since each command gets
+// its own file we link directly to that file rather than using a fragment anchor.
+func linkHandler(name string) string {
+	return name
+}
+
+// versionSuffix matches a trailing version string like " v1.2.3" or " v0.0.0-20260228210254-10ca5c6a64fb".
+var versionSuffix = regexp.MustCompile(` v\S+$`)
+
+// stripVersionFromShort removes the trailing version string from the root command's
+// Short description so that generated docs don't change with every build.
+func stripVersionFromShort(short string) string {
+	return versionSuffix.ReplaceAllString(short, "")
+}
+
+// setHiddenRecursive sets or clears the [cobra.Command.Hidden] flag on a command and all its children.
+func setHiddenRecursive(cmd *cobra.Command, hidden bool) {
+	cmd.Hidden = hidden
+
+	for _, child := range cmd.Commands() {
+		setHiddenRecursive(child, hidden)
+	}
+}
+
+// CheckOutputDir verifies the output directory state before generation.
+// If the directory exists and is non-empty, it either removes it (when Force is set)
+// or returns an actionable error suggesting --force / -f.
+func CheckOutputDir(fs opctx.FS, options *GenerateMarkdownOptions) error {
+	dirExists, err := fileutils.DirExists(fs, options.OutputDir)
+	if err != nil {
+		return fmt.Errorf("failed to check output directory %q:\n%w", options.OutputDir, err)
+	}
+
+	if !dirExists {
+		return nil
+	}
+
+	empty, err := fileutils.IsDirEmpty(fs, options.OutputDir)
+	if err != nil {
+		return fmt.Errorf("failed to check if output directory %q is empty:\n%w", options.OutputDir, err)
+	}
+
+	if empty {
+		return nil
+	}
+
+	if options.Force {
+		if err := fs.RemoveAll(options.OutputDir); err != nil {
+			return fmt.Errorf("failed to clean output directory %q:\n%w", options.OutputDir, err)
+		}
+
+		return nil
+	}
+
+	return fmt.Errorf(
+		"output directory %q already exists and is not empty;\n"+
+			"use --force / -f to delete and recreate it",
+		options.OutputDir)
+}
+
+// GenerateMarkdownDocs generates markdown documentation for the given command tree.
+func GenerateMarkdownDocs(fs opctx.FS, rootCmd *cobra.Command, options *GenerateMarkdownOptions) error {
+	// Strip the dynamic version string from the root command's Short description and disable
+	// the auto-generated date footer so that generated docs don't churn on every build.
+	origShort := rootCmd.Short
+	rootCmd.Short = stripVersionFromShort(origShort)
+	rootCmd.DisableAutoGenTag = true
+
+	defer func() {
+		rootCmd.Short = origShort
+		rootCmd.DisableAutoGenTag = false
+	}()
+
+	// Check the output directory state and handle force semantics.
+	err := CheckOutputDir(fs, options)
+	if err != nil {
+		return err
+	}
+
+	// Make sure the directory exists (it may have been removed by checkOutputDir, or may not exist yet).
+	err = fileutils.MkdirAll(fs, options.OutputDir)
 	if err != nil {
 		return fmt.Errorf("failed to ensure output directory %q exists:\n%w", options.OutputDir, err)
 	}
 
+	if options.IncludeHidden {
+		// Unhide all commands so they appear in the generated docs.
+		setHiddenRecursive(rootCmd, false)
+	}
+
 	// NOTE: This function can't work with our [opctx.FS] filesystem abstraction, but there's not much
 	// we can do about that.
-	err = doc.GenMarkdownTree(rootCmd, options.OutputDir)
+	err = doc.GenMarkdownTreeCustom(rootCmd, options.OutputDir, filePrepender, linkHandler)
 	if err != nil {
 		return fmt.Errorf("failed to generate markdown docs:\n%w", err)
 	}
diff --git a/internal/app/azldev/cmds/docs/markdown_test.go b/internal/app/azldev/cmds/docs/markdown_test.go
@@ -8,29 +8,100 @@ import (
 	"testing"
 
 	"github.com/gim-home/azldev-preview/internal/app/azldev/cmds/docs"
+	"github.com/gim-home/azldev-preview/internal/global/testctx"
+	"github.com/gim-home/azldev-preview/internal/utils/fileperms"
+	"github.com/gim-home/azldev-preview/internal/utils/fileutils"
+	"github.com/spf13/afero"
 	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
-func TestGenerateMarkdownDocs(t *testing.T) {
-	// Construct a test command.
-	cmd := &cobra.Command{
+// newTestCommand creates a minimal cobra command for testing doc generation.
+func newTestCommand() *cobra.Command {
+	return &cobra.Command{
 		Use:   "test",
 		Short: "A test command",
 	}
+}
+
+func TestGenerateMarkdownDocs(t *testing.T) {
+	// This integration test uses the host FS because cobra's doc.GenMarkdownTreeCustom
+	// writes directly to the real filesystem.
+	ctx := testctx.NewCtx(testctx.WithHostFS())
 
 	// Select an output dir that won't yet exist. This lets us make sure it will get created.
 	tempDir := t.TempDir()
 	outputDir := filepath.Join(tempDir, "docs")
 
-	err := docs.GenerateMarkdownDocs(cmd, &docs.GenerateMarkdownOptions{
+	err := docs.GenerateMarkdownDocs(ctx.FS(), newTestCommand(), &docs.GenerateMarkdownOptions{
 		OutputDir: outputDir,
 	})
 
 	require.NoError(t, err)
-	require.DirExists(t, outputDir)
+
+	exists, err := fileutils.DirExists(ctx.FS(), outputDir)
+	require.NoError(t, err)
+	assert.True(t, exists, "Expected output directory to exist")
 
 	matches, err := filepath.Glob(filepath.Join(outputDir, "*.md"))
 	require.NoError(t, err)
 	require.NotEmpty(t, matches, "Expected at least one markdown file to be generated")
 }
+
+func TestCheckOutputDir_NonExistentDir(t *testing.T) {
+	testFS := afero.NewMemMapFs()
+
+	err := docs.CheckOutputDir(testFS, &docs.GenerateMarkdownOptions{
+		OutputDir: "/does/not/exist",
+	})
+
+	require.NoError(t, err)
+}
+
+func TestCheckOutputDir_EmptyDirWithoutForce(t *testing.T) {
+	testFS := afero.NewMemMapFs()
+
+	require.NoError(t, fileutils.MkdirAll(testFS, "/output"))
+
+	err := docs.CheckOutputDir(testFS, &docs.GenerateMarkdownOptions{
+		OutputDir: "/output",
+		Force:     false,
+	})
+
+	require.NoError(t, err)
+}
+
+func TestCheckOutputDir_NonEmptyDirWithoutForce(t *testing.T) {
+	testFS := afero.NewMemMapFs()
+
+	require.NoError(t, fileutils.MkdirAll(testFS, "/output"))
+	require.NoError(t, fileutils.WriteFile(testFS, "/output/existing.txt", []byte("hello"), fileperms.PrivateFile))
+
+	err := docs.CheckOutputDir(testFS, &docs.GenerateMarkdownOptions{
+		OutputDir: "/output",
+		Force:     false,
+	})
+
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "--force")
+}
+
+func TestCheckOutputDir_NonEmptyDirWithForce(t *testing.T) {
+	testFS := afero.NewMemMapFs()
+
+	require.NoError(t, fileutils.MkdirAll(testFS, "/output"))
+	require.NoError(t, fileutils.WriteFile(testFS, "/output/existing.txt", []byte("hello"), fileperms.PrivateFile))
+
+	err := docs.CheckOutputDir(testFS, &docs.GenerateMarkdownOptions{
+		OutputDir: "/output",
+		Force:     true,
+	})
+
+	require.NoError(t, err)
+
+	// The directory should have been removed.
+	exists, err := fileutils.DirExists(testFS, "/output")
+	require.NoError(t, err)
+	assert.False(t, exists, "Expected output directory to be removed by --force")
+}
diff --git a/scenario/__snapshots__/TestMCPServerMode_1.snap.json b/scenario/__snapshots__/TestMCPServerMode_1.snap.json
@@ -262,6 +262,16 @@
        "description": "dry run only (do not take action)",
        "type": "boolean"
       },
+      "force": {
+       "default": false,
+       "description": "delete and recreate the output directory if it already exists",
+       "type": "boolean"
+      },
+      "include-hidden": {
+       "default": false,
+       "description": "include hidden commands in the generated docs",
+       "type": "boolean"
+      },
       "network-retries": {
        "default": 3,
        "description": "maximum number of attempts for network operations (minimum 1)",
