[Feature] Implement tool documentation generation CLI #88
Description
Overview
Implement CLI tool to auto-generate Field descriptions from docstring Args sections.
This is Phase 2 of ADR 003 (optional enhancement).
Context
See ADR 003 for full context: docs/architecture/decisions/003-automated-tool-documentation.md
Implementation guide available: docs/contributing/tool-documentation-guide.md
Scope
Reduce duplication between docstring Args sections and Pydantic Field(description=...) statements by auto-generating field descriptions from docstrings.
Components to Implement
1. Field Description Generator (utils/field_generator.py)
- Extract descriptions from docstring Args section
- Generate/update Pydantic
Field(description=...)statements - Preserve manual descriptions that add value beyond Args
- Use AST manipulation to modify Python files
Reference: Implementation guide Section 3 (lines 296-355)
2. Generation CLI (scripts/generate_field_docs.py)
Modes:
- Interactive: Review and approve each change
- Batch: Auto-apply all changes
- Dry-run: Show what would change without modifying files
Poe the Poet (version 0.37.0)
Error: Unrecognized task 'generate-field-docs'
Usage:
poe [global options] task [task arguments]
Global options:
-h, --help [TASK] Show this help page and exit, optionally supply a
task.
--version Print the version and exit
-v, --verbose Increase output (repeatable)
-q, --quiet Decrease output (repeatable)
-d, --dry-run Print the task contents but don't actually run it
-C, --directory PATH Specify where to find the pyproject.toml
-e, --executor EXECUTOR
Override the default task executor
--ansi Force enable ANSI output
--no-ansi Force disable ANSI output
Configured tasks:
format-python
format-python-check
format-markdown
format-markdown-check
format
format-check
lint-ty
lint-ruff
lint-ruff-fix
lint-yaml
lint
test
test-verbose
test-coverage
test-coverage-html
test-unit
test-integration
test-docs
test-no-docs
test-all
regenerate-client
validate-openapi
validate-openapi-redocly
docs-build
docs-clean
docs-serve
docs-autobuild
pre-commit-install
pre-commit-uninstall
pre-commit-run
pre-commit-update
check
fix
ci
prepare
validate-all
version-check
release-dry
analyze-coverage Analyze test coverage by file type (generated vs core logic)
help Show available tasks
clean Clean up build artifacts and cache files
Poe the Poet (version 0.37.0)
Error: Unrecognized task 'generate-field-docs'
Usage:
poe [global options] task [task arguments]
Global options:
-h, --help [TASK] Show this help page and exit, optionally supply a
task.
--version Print the version and exit
-v, --verbose Increase output (repeatable)
-q, --quiet Decrease output (repeatable)
-d, --dry-run Print the task contents but don't actually run it
-C, --directory PATH Specify where to find the pyproject.toml
-e, --executor EXECUTOR
Override the default task executor
--ansi Force enable ANSI output
--no-ansi Force disable ANSI output
Configured tasks:
format-python
format-python-check
format-markdown
format-markdown-check
format
format-check
lint-ty
lint-ruff
lint-ruff-fix
lint-yaml
lint
test
test-verbose
test-coverage
test-coverage-html
test-unit
test-integration
test-docs
test-no-docs
test-all
regenerate-client
validate-openapi
validate-openapi-redocly
docs-build
docs-clean
docs-serve
docs-autobuild
pre-commit-install
pre-commit-uninstall
pre-commit-run
pre-commit-update
check
fix
ci
prepare
validate-all
version-check
release-dry
analyze-coverage Analyze test coverage by file type (generated vs core logic)
help Show available tasks
clean Clean up build artifacts and cache files
Poe the Poet (version 0.37.0)
Error: Unrecognized task 'generate-field-docs'
Usage:
poe [global options] task [task arguments]
Global options:
-h, --help [TASK] Show this help page and exit, optionally supply a
task.
--version Print the version and exit
-v, --verbose Increase output (repeatable)
-q, --quiet Decrease output (repeatable)
-d, --dry-run Print the task contents but don't actually run it
-C, --directory PATH Specify where to find the pyproject.toml
-e, --executor EXECUTOR
Override the default task executor
--ansi Force enable ANSI output
--no-ansi Force disable ANSI output
Configured tasks:
format-python
format-python-check
format-markdown
format-markdown-check
format
format-check
lint-ty
lint-ruff
lint-ruff-fix
lint-yaml
lint
test
test-verbose
test-coverage
test-coverage-html
test-unit
test-integration
test-docs
test-no-docs
test-all
regenerate-client
validate-openapi
validate-openapi-redocly
docs-build
docs-clean
docs-serve
docs-autobuild
pre-commit-install
pre-commit-uninstall
pre-commit-run
pre-commit-update
check
fix
ci
prepare
validate-all
version-check
release-dry
analyze-coverage Analyze test coverage by file type (generated vs core logic)
help Show available tasks
clean Clean up build artifacts and cache files
3. Safety Checks
- Only update Field() if description is missing or generic
- Preserve hand-written descriptions that add context
- Validate generated code with AST parsing
- Run validation after generation to ensure correctness
Tasks
- Implement
utils/field_generator.py - Implement
scripts/generate_field_docs.py - Add interactive approval workflow
- Add dry-run mode
- Add batch mode with --auto-approve flag
- Add poe task:
uv run poe generate-field-docs - Document usage in contributing guide
- Test on sample tools
Acceptance Criteria
- Correctly extracts descriptions from Args sections
- Only updates missing/generic Field descriptions
- Preserves valuable hand-written descriptions
- Interactive mode shows clear diffs
- Dry-run mode shows changes without applying
- Batch mode works for CI/CD integration
- Generated code passes validation (Issue [Feature] Implement tool documentation validation #87)
Testing Plan
- Create test tool with missing Field descriptions
- Verify generation creates correct descriptions
- Create tool with valuable hand-written descriptions
- Verify generation preserves them
- Test interactive approval workflow
- Test dry-run shows accurate changes
- Test batch mode with --auto-approve
Dependencies
- Requires: [Feature] Implement tool documentation validation #87 (validation) for post-generation validation
- Requires: [ADR] Document automated tool documentation strategy #85 (ADR 003) for context
- Optional: Can be implemented independently of [Feature] Implement tool documentation generation CLI #88 (pre-commit)
Related
- ADR 002: Documents the Field pattern we're generating
- ADR 003: Documents overall strategy (Phase 2)
- Issue [Feature] Implement tool documentation validation #87: Validation ensures generated docs are correct
Labels
enhancement