feat: Add automated CLI documentation generator

[johndmulhausen]

Summary

This PR introduces an automated CLI documentation generator for the W&B CLI reference documentation. The new script introspects the W&B CLI structure and generates Hugo-compatible markdown documentation automatically.

Changes

New Script: /scripts/cli-docs-generator.py

A Python script that:

• Introspects the W&B CLI using the Click framework
• Generates structured markdown documentation with Hugo front matter
• Creates a hierarchical directory structure for nested commands
• Preserves formatting and paragraph breaks from original docstrings

Key Features

• Automatic Structure Discovery: Extracts command hierarchy, options, arguments, and help text directly from the CLI code
• Hugo Integration: Generates proper front matter with title and no_list directives
• Clean Output:
  • Brief descriptions in command tables (first sentence only)
  • Full descriptions preserved on individual command pages
  • Removed generic "Examples" sections that only showed --help
• Robust File Management:
  • Clears entire output directory before regeneration to prevent vestigial files
  • Maintains consistent file naming (e.g., wandb-artifact-cache-cleanup.md)
• User Control:
  • Default: Auto-overwrites existing documentation
  • -i/--interactive: Prompts for confirmation before overwriting
  • -o/--output: Custom output directory option

Documentation Updates

• Updated all 40 CLI documentation files with consistent formatting
• Added 4 new command pages that were previously missing:
  • wandb-local.md
  • wandb-off.md
  • wandb-on.md
  • wandb-projects.md
• Improved readability with preserved whitespace and paragraph breaks
• Alphabetical ordering throughout (no weight front matter)

Usage

Run the script from the project root:

# Default: Auto-generate and overwrite
python scripts/cli-docs-generator.py

# Interactive mode (prompts before overwriting)
python scripts/cli-docs-generator.py -i

# Custom output directory
python scripts/cli-docs-generator.py -o /path/to/output

Benefits

• Maintainability: Documentation stays in sync with CLI implementation
• Consistency: All pages follow the same format and structure
• Completeness: Automatically discovers and documents all commands
• Accuracy: Documentation is extracted directly from the source code

Testing

The script has been tested and successfully generates documentation for all W&B CLI commands, including nested command groups like wandb artifact cache cleanup.

📄 View preview links for changed pages

[cloudflare-workers-and-pages]

Deploying docs with    Cloudflare Pages

Latest commit:	9cc1f18
Status:	✅  Deploy successful!
Preview URL:	https://3322712f.docodile.pages.dev
Branch Preview URL:	https://feat-cli-docs-generator.docodile.pages.dev

View logs

[github-actions]

PR Preview: Changed content

Base preview: https://feat-cli-docs-generator.docodile.pages.dev

Added

Title	Path
wandb local	content/en/ref/cli/wandb-local.md
wandb off	content/en/ref/cli/wandb-off.md
wandb on	content/en/ref/cli/wandb-on.md
wandb projects	content/en/ref/cli/wandb-projects.md

Modified

Title	Path
Command Line Interface	content/en/ref/cli/_index.md
wandb agent	content/en/ref/cli/wandb-agent.md
wandb artifact	content/en/ref/cli/wandb-artifact/_index.md
wandb artifact cache	content/en/ref/cli/wandb-artifact/wandb-artifact-cache/_index.md
wandb artifact cache cleanup	content/en/ref/cli/wandb-artifact/wandb-artifact-cache/wandb-artifact-cache-cleanup.md
wandb artifact get	content/en/ref/cli/wandb-artifact/wandb-artifact-get.md
wandb artifact ls	content/en/ref/cli/wandb-artifact/wandb-artifact-ls.md
wandb artifact put	content/en/ref/cli/wandb-artifact/wandb-artifact-put.md
wandb beta	content/en/ref/cli/wandb-beta/_index.md
wandb beta sync	content/en/ref/cli/wandb-beta/wandb-beta-sync.md
wandb controller	content/en/ref/cli/wandb-controller.md
wandb disabled	content/en/ref/cli/wandb-disabled.md
wandb docker-run	content/en/ref/cli/wandb-docker-run.md
wandb docker	content/en/ref/cli/wandb-docker.md
wandb enabled	content/en/ref/cli/wandb-enabled.md
wandb init	content/en/ref/cli/wandb-init.md
wandb job	content/en/ref/cli/wandb-job/_index.md
wandb job create	content/en/ref/cli/wandb-job/wandb-job-create.md
wandb job describe	content/en/ref/cli/wandb-job/wandb-job-describe.md
wandb job list	content/en/ref/cli/wandb-job/wandb-job-list.md
wandb launch-agent	content/en/ref/cli/wandb-launch-agent.md
wandb launch-sweep	content/en/ref/cli/wandb-launch-sweep.md
wandb launch	content/en/ref/cli/wandb-launch.md
wandb login	content/en/ref/cli/wandb-login.md
wandb offline	content/en/ref/cli/wandb-offline.md
wandb online	content/en/ref/cli/wandb-online.md
wandb pull	content/en/ref/cli/wandb-pull.md
wandb restore	content/en/ref/cli/wandb-restore.md
wandb scheduler	content/en/ref/cli/wandb-scheduler.md
wandb server	content/en/ref/cli/wandb-server/_index.md
wandb server start	content/en/ref/cli/wandb-server/wandb-server-start.md
wandb server stop	content/en/ref/cli/wandb-server/wandb-server-stop.md
wandb status	content/en/ref/cli/wandb-status.md
wandb sweep	content/en/ref/cli/wandb-sweep.md
wandb sync	content/en/ref/cli/wandb-sync.md
wandb verify	content/en/ref/cli/wandb-verify.md

[mdlinville]

I hard-reset to main, put back your script, updated it for Mintlify, and regenerated the refs for 0.23.0. Those are the commits at the tip, PTAL. I can see that we still have some broken links that I didn't see locally, I will review it more carefully tomorrow morning if you don't get a chance first.

[mdlinville]

Closing this to get the Mintlify checks to run in a new PR against the same branch.