Enhancement: Comprehensive Documentation Generation for Generated Code

[dougborg]

Summary

Extend the generated Python client with comprehensive documentation generation capabilities, building on the docstring improvements requested in #85.

Current State

• Issue description and / or title of properties and endpoints #85 requests better docstrings for properties and endpoints from OpenAPI schema descriptions
• Generated code currently has minimal documentation
• Users must manually document the generated API clients
• No automated way to produce comprehensive API documentation from the generated code

Proposed Enhancement

Generate complete documentation packages alongside the Python client code, leveraging both the OpenAPI schema information and the generated Python code structure.

Goals

1. Enhanced Docstrings (builds on description and / or title of properties and endpoints #85):

   • Extract and include title and description from OpenAPI schema for all properties
   • Add comprehensive docstrings for service endpoints with parameter descriptions
   • Include return type documentation with response schema details
   • Document authentication requirements and error responses

2. Documentation Generation:

   • Generate Sphinx-compatible documentation structure
   • Support mkdocs output format as alternative
   • Include auto-generated API reference from Python docstrings
   • Create user guides with code examples for each endpoint

3. Rich Content:

   • Generate markdown documentation from OpenAPI schema
   • Include request/response examples from OpenAPI examples
   • Create usage guides with authentication setup
   • Generate type reference documentation

Implementation Ideas

1. Template Extensions:

   • Enhance existing Jinja templates to include comprehensive docstrings
   • Add new templates for documentation generation (conf.py, index.rst, etc.)
   • Template for mkdocs.yml configuration

2. Documentation Modules:

   • Add --generate-docs flag to CLI
   • Support --docs-format choice between sphinx/mkdocs
   • Include documentation build scripts in generated output

3. Content Generation:

   • Parse OpenAPI examples and convert to Python code examples
   • Generate endpoint-specific usage guides
   • Create comprehensive type documentation

Example Output Structure

generated_client/
├── client/           # Generated Python code (existing)
├── docs/
│   ├── conf.py       # Sphinx configuration
│   ├── index.rst     # Main documentation index
│   ├── api/          # Auto-generated API reference
│   ├── guides/       # Usage guides per endpoint
│   └── examples/     # Code examples
├── mkdocs.yml        # Alternative mkdocs config
└── README.md         # Enhanced with documentation links

Dependencies

• Depends on description and / or title of properties and endpoints #85 for foundational docstring improvements
• Should be compatible with existing --use-pydantic-v2 and --use-orjson flags
• Consider integration with existing template system

Benefits

• Self-documenting generated clients
• Reduced manual documentation effort for API consumers
• Professional-quality documentation output
• Better developer experience with generated clients

Open Questions

1. Should documentation generation be opt-in via CLI flag or always generated?
2. Preference for default format: Sphinx vs mkdocs?
3. Should we generate interactive documentation (like Swagger UI) as well?
4. How to handle custom template modifications while preserving doc generation?

Related Issues

• description and / or title of properties and endpoints #85 (docstring improvements - prerequisite)
• Documentation & error message unclear when trying to generate for urllib #74 (documentation clarity for the generator itself)

This enhancement would significantly improve the value proposition of generated clients by providing comprehensive, professional documentation out of the box.