persona-community-5/.claude/commands/generate-docs.md

Generate API Documentation

Regenerate the Slate API documentation from OpenAPI specs.

Usage

Run this command when you need to preview documentation changes locally or after modifying OpenAPI specs.

Steps

1. Ensure services are running locally

   ./scripts/dev.sh
   

2. Generate markdown from OpenAPI specs

   chmod +x docs/scripts/generate-docs.sh
   ./docs/scripts/generate-docs.sh http://localhost
   

3. Build Slate documentation locally (optional)

   cd docs
   bundle install
   bundle exec middleman serve
   

   Then open http://localhost:4567 to preview.

What This Does

1. Discovers all services with OpenAPI specs
2. Fetches /openapi.json from each running service
3. Converts specs to Slate markdown using Widdershins
4. Updates docs/source/includes/ with service documentation

CI Pipeline

In production, this process runs automatically:

• CI fetches OpenAPI specs from built service binaries
• Widdershins converts to Slate markdown
• Middleman builds static HTML
• Static files deployed to docs.{domain}

Troubleshooting

• "Connection refused": Ensure services are running on expected ports
• "No OpenAPI spec found": Check that services expose /openapi.json
• "widdershins not found": Run npm install -g widdershins
• "bundle not found": Install Ruby and run gem install bundler