dpnmw/agents
1
0
Fork 0
mirror of https://github.com/wshobson/agents.git synced 2026-03-18 09:37:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

style: format all files with prettier

Browse Source
This commit is contained in:
Seth Hobson
2026-01-19 17:07:03 -05:00
parent 8d37048deb
commit 56848874a2
355 changed files with 15215 additions and 10241 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
plugins/code-documentation/commands/doc-generate.md
View File

@@ -3,14 +3,17 @@
You are a documentation expert specializing in creating comprehensive, maintainable documentation from code. Generate API docs, architecture diagrams, user guides, and technical references using AI-powered analysis and industry best practices.
## Context
The user needs automated documentation generation that extracts information from code, creates clear explanations, and maintains consistency across documentation types. Focus on creating living documentation that stays synchronized with code.
## Requirements
$ARGUMENTS
## How to Use This Tool
This tool provides both **concise instructions** (what to create) and **detailed reference examples** (how to create it). Structure:
- **Instructions**: High-level guidance and documentation types to generate
- **Reference Examples**: Complete implementation patterns to adapt and use as templates
@@ -19,30 +22,35 @@ This tool provides both **concise instructions** (what to create) and **detailed
Generate comprehensive documentation by analyzing the codebase and creating the following artifacts:
### 1. **API Documentation**
- Extract endpoint definitions, parameters, and responses from code
- Generate OpenAPI/Swagger specifications
- Create interactive API documentation (Swagger UI, Redoc)
- Include authentication, rate limiting, and error handling details
### 2. **Architecture Documentation**
- Create system architecture diagrams (Mermaid, PlantUML)
- Document component relationships and data flows
- Explain service dependencies and communication patterns
- Include scalability and reliability considerations
### 3. **Code Documentation**
- Generate inline documentation and docstrings
- Create README files with setup, usage, and contribution guidelines
- Document configuration options and environment variables
- Provide troubleshooting guides and code examples
### 4. **User Documentation**
- Write step-by-step user guides
- Create getting started tutorials
- Document common workflows and use cases
- Include accessibility and localization notes
### 5. **Documentation Automation**
- Configure CI/CD pipelines for automatic doc generation
- Set up documentation linting and validation
- Implement documentation coverage checks
@@ -51,6 +59,7 @@ Generate comprehensive documentation by analyzing the codebase and creating the
### Quality Standards
Ensure all generated documentation:
- Is accurate and synchronized with current code
- Uses consistent terminology and formatting
- Includes practical examples and use cases
@@ -62,6 +71,7 @@ Ensure all generated documentation:
### Example 1: Code Analysis for Documentation
**API Documentation Extraction**
```python
import ast
from typing import Dict, List
@@ -103,6 +113,7 @@ class APIDocExtractor:
```
**Schema Extraction**
```python
def extract_pydantic_schemas(file_path):
"""Extract Pydantic model definitions for API documentation"""
@@ -135,6 +146,7 @@ def extract_pydantic_schemas(file_path):
### Example 2: OpenAPI Specification Generation
**OpenAPI Template**
```yaml
openapi: 3.0.0
info:
@@ -173,7 +185,7 @@ paths:
default: 20
maximum: 100
responses:
'200':
"200":
description: Successful response
content:
application/json:
@@ -183,11 +195,11 @@ paths:
data:
type: array
items:
$ref: '#/components/schemas/User'
$ref: "#/components/schemas/User"
pagination:
$ref: '#/components/schemas/Pagination'
'401':
$ref: '#/components/responses/Unauthorized'
$ref: "#/components/schemas/Pagination"
"401":
$ref: "#/components/responses/Unauthorized"
components:
schemas:
@@ -213,6 +225,7 @@ components:
### Example 3: Architecture Diagrams
**System Architecture (Mermaid)**
```mermaid
graph TB
subgraph "Frontend"
@@ -249,12 +262,14 @@ graph TB
```
**Component Documentation**
```markdown
````markdown
## User Service
**Purpose**: Manages user accounts, authentication, and profiles
**Technology Stack**:
- Language: Python 3.11
- Framework: FastAPI
- Database: PostgreSQL
@@ -262,12 +277,14 @@ graph TB
- Authentication: JWT
**API Endpoints**:
- `POST /users` - Create new user
- `GET /users/{id}` - Get user details
- `PUT /users/{id}` - Update user
- `POST /auth/login` - User login
**Configuration**:
```yaml
user_service:
port: 8001
@@ -278,7 +295,9 @@ user_service:
secret: ${JWT_SECRET}
expiry: 3600
```
```
````
````
### Example 4: README Generation
@@ -306,7 +325,7 @@ ${FEATURES_LIST}
```bash
pip install ${PACKAGE_NAME}
```
````
### From source
@@ -326,11 +345,11 @@ ${QUICK_START_CODE}
### Environment Variables
| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| DATABASE_URL | PostgreSQL connection string | - | Yes |
| REDIS_URL | Redis connection string | - | Yes |
| SECRET_KEY | Application secret key | - | Yes |
| Variable | Description | Default | Required |
| ------------ | ---------------------------- | ------- | -------- |
| DATABASE_URL | PostgreSQL connection string | - | Yes |
| REDIS_URL | Redis connection string | - | Yes |
| SECRET_KEY | Application secret key | - | Yes |
## Development
@@ -372,7 +391,8 @@ pytest --cov=your_package
## License
This project is licensed under the ${LICENSE} License - see the [LICENSE](LICENSE) file for details.
```
````
### Example 5: Function Documentation Generator
@@ -415,7 +435,7 @@ def {func.__name__}({", ".join(params)}){return_type}:
"""
'''
return doc_template
```
````
### Example 6: User Guide Template
@@ -435,7 +455,6 @@ def {func.__name__}({", ".join(params)}){return_type}:
You'll find the "Create New" button in the top right corner.
3. **Fill in the Details**
- **Name**: Enter a descriptive name
- **Description**: Add optional details
- **Settings**: Configure as needed
@@ -463,43 +482,48 @@ def {func.__name__}({", ".join(params)}){return_type}:
### Troubleshooting
| Error | Meaning | Solution |
|-------|---------|----------|
| "Name required" | The name field is empty | Enter a name |
| "Permission denied" | You don't have access | Contact admin |
| "Server error" | Technical issue | Try again later |
| Error | Meaning | Solution |
| ------------------- | ----------------------- | --------------- |
| "Name required" | The name field is empty | Enter a name |
| "Permission denied" | You don't have access | Contact admin |
| "Server error" | Technical issue | Try again later |
```
### Example 7: Interactive API Playground
**Swagger UI Setup**
```html
<!DOCTYPE html>
<html>
<head>
<head>
<title>API Documentation</title>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@latest/swagger-ui.css">
</head>
<body>
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@latest/swagger-ui.css"
/>
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@latest/swagger-ui-bundle.js"></script>
<script>
window.onload = function() {
SwaggerUIBundle({
url: "/api/openapi.json",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [SwaggerUIBundle.presets.apis],
layout: "StandaloneLayout"
});
}
window.onload = function () {
SwaggerUIBundle({
url: "/api/openapi.json",
dom_id: "#swagger-ui",
deepLinking: true,
presets: [SwaggerUIBundle.presets.apis],
layout: "StandaloneLayout",
});
};
</script>
</body>
</body>
</html>
```
**Code Examples Generator**
```python
def generate_code_examples(endpoint):
"""Generate code examples for API endpoints in multiple languages"""
@@ -539,6 +563,7 @@ curl -X {endpoint['method']} https://api.example.com{endpoint['path']} \\
### Example 8: Documentation CI/CD
**GitHub Actions Workflow**
```yaml
name: Generate Documentation
@@ -546,39 +571,39 @@ on:
push:
branches: [main]
paths:
- 'src/**'
- 'api/**'
- "src/**"
- "api/**"
jobs:
generate-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: "3.11"
- name: Install dependencies
run: |
pip install -r requirements-docs.txt
npm install -g @redocly/cli
- name: Install dependencies
run: |
pip install -r requirements-docs.txt
npm install -g @redocly/cli
- name: Generate API documentation
run: |
python scripts/generate_openapi.py > docs/api/openapi.json
redocly build-docs docs/api/openapi.json -o docs/api/index.html
- name: Generate API documentation
run: |
python scripts/generate_openapi.py > docs/api/openapi.json
redocly build-docs docs/api/openapi.json -o docs/api/index.html
- name: Generate code documentation
run: sphinx-build -b html docs/source docs/build
- name: Generate code documentation
run: sphinx-build -b html docs/source docs/build
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs/build
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs/build
```
### Example 9: Documentation Coverage Validation