generate-api-docs

name	generate-api-docs
description	Generate API documentation from Python docstrings using pdoc, sphinx, or mkdocs. This skill should be used when the user wants to create browsable HTML API documentation from existing Python code, generate reference docs for a package, or set up automated documentation for a project. Trigger phrases include "generate API docs", "create documentation", "build docs from docstrings".
context	fork
agent	general-purpose
model	sonnet
argument-hint	<package-path> [--format=pdoc|sphinx|mkdocs]
allowed-tools	["Glob","Read","Write","Edit","Bash(uv:*)","Bash(pdoc:*)","Bash(sphinx-*:*)","Bash(mkdocs:*)","Bash(python:*)","TodoWrite"]

Generate API Documentation

Overview

Generate comprehensive API documentation from Python docstrings using automated documentation tools. The skill supports multiple documentation generators (pdoc, sphinx, mkdocs), handles monorepo structures, and creates browsable HTML documentation with navigation and index files.

Input Parsing

Parse the user's input to extract:

1. Package path: Directory containing Python packages (e.g., packages/tensorlogic-core/src)
2. Format option (optional): --format=pdoc (default), --format=sphinx, or --format=mkdocs

Default to pdoc if no format is specified.

Workflow

1. Discovery Phase

Create a TodoWrite list with these items:

• Discover Python packages
• Check/install documentation tool
• Generate documentation
• Create index/overview
• Validate output

Mark the first item as in_progress.

Use Glob to find all Python packages in the specified path by looking for __init__.py files:

**/__init__.py

Identify the package structure and determine which packages should be documented.

2. Check and Install Documentation Tool

For pdoc (default, recommended for Google-style docstrings):

uv run pdoc --version

If not available:

uv add --dev pdoc

For sphinx:

uv run sphinx-build --version

If not available:

uv add --dev sphinx sphinx-rtd-theme

For mkdocs:

uv run mkdocs --version

If not available:

uv add --dev mkdocs mkdocstrings[python]

Mark this todo item as completed.

3. Generate Documentation

Mark the "Generate documentation" todo as in_progress.

Using pdoc (default):

For a single package:

uv run pdoc <package-name> -o docs/api

For multiple packages in a monorepo:

uv run pdoc tensorlogic.estate tensorlogic.validation -o docs/api

Using sphinx:

Initialize sphinx if needed:

cd docs && uv run sphinx-quickstart

Generate API docs:

uv run sphinx-apidoc -o docs/source <package-path>
uv run sphinx-build -b html docs/source docs/build

Using mkdocs:

Generate with mkdocstrings plugin:

uv run mkdocs build

Mark this todo item as completed.

4. Create Documentation Index

Mark the "Create index/overview" todo as in_progress.

Generate a docs/api/index.md or docs/api/README.md with:

• Overview of the documented packages
• Links to main modules
• Quick start examples
• Navigation guide

Example index.md template:

# <Project Name> API Documentation

Auto-generated API documentation from Python docstrings.

## Packages

### <package-name>
<Brief description>
- [Core module](path/to/core.html)
- [Schemas](path/to/schemas.html)
- [Utilities](path/to/utils.html)

## Quick Start

\`\`\`python
from <package> import <class>

# Example usage
example = <class>()
result = example.method()
\`\`\`

## Navigation

- Browse the sidebar for full module listing
- Use the search box to find specific functions/classes
- Click module names to see detailed API reference

---

*Generated on {current_date} from source docstrings*

Mark this todo item as completed.

5. Validate Output

Mark the "Validate output" todo as in_progress.

Check that documentation was generated:

• Verify HTML/markdown files exist in output directory
• Check that key modules are documented
• Report any warnings from the documentation generator
• Note any packages with missing docstrings

Mark this todo item as completed.

6. Completion Report

Provide the user with:

1. Location: Path to generated documentation
2. View command: How to view locally

   python -m http.server -d docs/api 8000
   # Then visit http://localhost:8000
   

3. Summary: Number of packages/modules documented
4. Warnings: Any missing docstrings or documentation issues
5. Next steps: Suggestions for integration

Configuration Files

If creating new documentation setup, create appropriate config files:

For sphinx - docs/conf.py:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',  # Google-style docstrings
    'sphinx.ext.viewcode',
]
napoleon_google_docstring = True
html_theme = 'sphinx_rtd_theme'

For mkdocs - mkdocs.yml:

site_name: <Project Name> API
plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          options:
            docstring_style: google
            show_source: true

Output Structure

Typical documentation output structure:

docs/
├── api/
│   ├── index.md              # Overview and navigation
│   ├── <package>/
│   │   ├── module1.html
│   │   ├── module2.html
│   │   └── subpackage/
│   │       └── module3.html
│   └── search.html          # Search functionality

Monorepo Best Practices

For Nx monorepos or multi-package projects:

Option 1: Per-package docs (separate documentation for each package)

uv run pdoc tensorlogic-core -o docs/api/tensorlogic-core
uv run pdoc authority -o docs/api/authority

Option 2: Unified docs (combined into one documentation site)

uv run pdoc tensorlogic authority rulepacks -o docs/api

Option 3: Versioned docs (commit to repository)

• Keep docs/api/ in git for GitHub Pages
• Add build step to CI/CD

Option 4: Generated on demand (add to .gitignore)

• Add docs/api/ to .gitignore
• Generate locally or in CI/CD pipelines

Nx Integration Suggestion

After successful generation, suggest adding a docs target to project.json:

{
  "targets": {
    "docs": {
      "executor": "nx:run-commands",
      "options": {
        "command": "uv run pdoc <package-name> -o docs/api",
        "cwd": "packages/<package-dir>"
      }
    }
  }
}

Then users can run:

nx run <package-name>:docs

Important Notes

• Work through the todo list systematically
• Use uv for all Python commands to respect workspace environment
• If docstrings are missing, suggest running the add-docstrings skill first
• For large monorepos, consider generating docs per package rather than all at once
• pdoc is recommended for projects using Google-style docstrings (no configuration needed)
• sphinx is recommended for projects needing extensive customization
• mkdocs is recommended for projects wanting markdown-based documentation