Automatically generate and maintain comprehensive technical documentation, tutorials, and knowledge bases to improve transparency and developer onboarding.
Automatically generate and maintain comprehensive technical documentation, tutorials, and knowledge bases to improve transparency and developer onboarding.
/plugin marketplace add SuperClaude-Org/SuperClaude_Plugin/plugin install sc@superclaudeAutomatically generate and maintain comprehensive technical documentation, tutorials, and knowledge bases to improve transparency and developer onboarding.
/sc:document generate - Full documentation suite/sc:document api-docs - API reference generation/sc:document tutorial - Tutorial creation/sc:document readme - README generation@agent-documentation-specialist - Direct activationClear & Structured:
Generated From:
Output Format: Markdown with automatic cross-linking
Example:
# API Reference
## Authentication Module
### `jwt_handler.generate_token()`
Generate a JWT access token for authenticated user.
**Parameters**:
- `user_id` (str): Unique user identifier
- `expires_in` (int, optional): Token expiration in seconds. Default: 3600
**Returns**:
- `str`: Encoded JWT token
**Raises**:
- `ValueError`: If user_id is invalid
- `TokenGenerationError`: If token creation fails
**Example**:
```python
from auth.jwt_handler import generate_token
# Generate token for user
token = generate_token(user_id="user_123", expires_in=7200)
print(f"Access token: {token}")
Security Considerations:
See Also:
validate_token() - Token validation
### 2. README Generation
**Sections Automatically Generated**:
- Project overview and description
- Installation instructions
- Quick start guide
- Feature list
- Configuration options
- Usage examples
- Contributing guidelines
- License information
**Example Output**:
```markdown
# MyFastAPIApp
Modern FastAPI application with JWT authentication and PostgreSQL database.
## 🚀 Quick Start
### Prerequisites
- Python 3.11+
- PostgreSQL 14+
- Redis 7+ (for caching)
### Installation
1. **Clone the repository**
```bash
git clone https://github.com/user/my-fastapi-app.git
cd my-fastapi-app
Install dependencies
poetry install
Set up environment
cp .env.example .env
# Edit .env with your configuration
Run database migrations
alembic upgrade head
Start the server
uvicorn main:app --reload
Visit http://localhost:8000/docs for interactive API documentation.
my-fastapi-app/
├── src/
│ ├── api/ # API endpoints
│ ├── auth/ # Authentication logic
│ ├── db/ # Database models
│ └── services/ # Business logic
├── tests/ # Test suite
├── docs/ # Documentation
└── alembic/ # Database migrations
Run the test suite:
pytest
With coverage:
pytest --cov=src --cov-report=html
MIT License - see LICENSE file.
### 3. Architecture Documentation
**Auto-generated Diagrams**:
- System architecture
- Database schema
- API flow diagrams
- Component relationships
**Example**:
```markdown
# Architecture Overview
## System Architecture
```mermaid
graph TB
Client[Client App]
API[FastAPI Server]
Auth[Auth Service]
DB[(PostgreSQL)]
Cache[(Redis)]
Client -->|HTTP/HTTPS| API
API -->|Validate Token| Auth
API -->|Query Data| DB
API -->|Cache| Cache
Auth -->|Store Sessions| Cache
erDiagram
USER ||--o{ SESSION : has
USER {
uuid id PK
string email UK
string password_hash
datetime created_at
datetime updated_at
}
SESSION {
uuid id PK
uuid user_id FK
string token
datetime expires_at
datetime created_at
}
sequenceDiagram
participant Client
participant API
participant Auth
participant DB
participant Cache
Client->>API: POST /auth/login
API->>DB: Query user by email
DB-->>API: User data
API->>Auth: Verify password
Auth-->>API: Password valid
API->>Auth: Generate JWT
Auth-->>API: Access + Refresh tokens
API->>Cache: Store session
API-->>Client: Return tokens
### 4. Tutorial Generation
**Auto-generated from Code Patterns**:
```markdown
# Tutorial: Implementing JWT Authentication
## Overview
This tutorial will guide you through implementing JWT authentication in your FastAPI application.
**What you'll learn**:
- Generate and validate JWT tokens
- Protect API endpoints
- Implement refresh token mechanism
- Handle token expiration
**Prerequisites**:
- FastAPI application set up
- Python 3.11+
- Basic understanding of HTTP authentication
**Estimated time**: 30 minutes
## Step 1: Install Dependencies
```bash
poetry add pyjwt passlib[bcrypt]
Create src/config/security.py:
from pydantic_settings import BaseSettings
class SecuritySettings(BaseSettings):
SECRET_KEY: str
ALGORITHM: str = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES: int = 15
REFRESH_TOKEN_EXPIRE_DAYS: int = 7
class Config:
env_file = ".env"
settings = SecuritySettings()
Create src/auth/jwt_handler.py:
from datetime import datetime, timedelta
import jwt
from config.security import settings
def generate_token(user_id: str, expires_in: int = None) -> str:
"""Generate JWT access token"""
if expires_in is None:
expires_in = settings.ACCESS_TOKEN_EXPIRE_MINUTES * 60
payload = {
"user_id": user_id,
"exp": datetime.utcnow() + timedelta(seconds=expires_in),
"iat": datetime.utcnow()
}
return jwt.encode(
payload,
settings.SECRET_KEY,
algorithm=settings.ALGORITHM
)
def validate_token(token: str) -> dict:
"""Validate JWT token"""
try:
payload = jwt.decode(
token,
settings.SECRET_KEY,
algorithms=[settings.ALGORITHM]
)
return payload
except jwt.ExpiredSignatureError:
raise ValueError("Token expired")
except jwt.JWTError:
raise ValueError("Invalid token")
Create authentication dependency in src/auth/dependencies.py:
from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
from .jwt_handler import validate_token
security = HTTPBearer()
async def get_current_user(
credentials: HTTPAuthorizationCredentials = Depends(security)
) -> dict:
"""Extract and validate user from JWT"""
try:
payload = validate_token(credentials.credentials)
return payload
except ValueError as e:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail=str(e)
)
Update src/api/routes.py:
from fastapi import APIRouter, Depends
from auth.dependencies import get_current_user
router = APIRouter()
@router.get("/protected")
async def protected_route(user: dict = Depends(get_current_user)):
"""Protected endpoint requiring authentication"""
return {
"message": "Access granted",
"user_id": user["user_id"]
}
Create tests/test_auth.py:
import pytest
from auth.jwt_handler import generate_token, validate_token
def test_generate_and_validate_token():
"""Test token generation and validation"""
user_id = "user_123"
token = generate_token(user_id)
payload = validate_token(token)
assert payload["user_id"] == user_id
def test_expired_token():
"""Test expired token rejection"""
token = generate_token("user_123", expires_in=-1)
with pytest.raises(ValueError, match="Token expired"):
validate_token(token)
Related Guides:
## Command Implementation
### /sc:document - Documentation Command
```markdown
# Usage
/sc:document <type> [target] [--flags]
# Types
- `generate` - Full documentation suite
- `api` - API reference from code
- `readme` - README.md generation
- `tutorial` - Usage tutorial creation
- `architecture` - System architecture docs
- `changelog` - Generate CHANGELOG.md
- `migration` - Migration guide for version update
# Targets
- File path, directory, or module name
- Examples: `src/api/`, `auth.jwt_handler`, `main.py`
# Flags
- `--lang <code>` - Language (en, ja, zh, ko). Default: en
- `--format <type>` - Output format (md, html, pdf). Default: md
- `--update` - Update existing docs instead of creating new
- `--interactive` - Interactive mode with prompts
- `--output <path>` - Custom output directory
# Examples
## Generate Complete Documentation Suite
/sc:document generate
## API Documentation for Module
/sc:document api src/api/ --format html
## README for Project
/sc:document readme --interactive
## Tutorial for Feature
/sc:document tutorial authentication
## Architecture with Diagrams
/sc:document architecture --format pdf
## Changelog from Git History
/sc:document changelog --since v1.0.0
## Japanese Documentation
/sc:document api src/auth/ --lang ja
## Update Existing Docs
/sc:document api src/api/ --update
📚 **Documentation Generation Started**
Analyzing project structure...
✓ Found 234 files across 47 modules
### 📋 Documentation Plan
1. README.md - Project overview
2. docs/api/ - API reference (47 modules)
3. docs/guides/ - User guides (5 topics)
4. docs/architecture/ - System diagrams
5. CHANGELOG.md - Version history
Estimated time: 3-5 minutes
### 🔄 Progress
[████████████████░░░░] 80%
✓ README.md generated (2.3s)
✓ API documentation (187 functions, 34 classes) (15.7s)
✓ Architecture diagrams (3 diagrams) (4.2s)
⏳ User guides (3/5 complete)
⏳ Changelog (processing 247 commits)
### 📊 Results
**Files Created**: 73 documentation files
**Total Size**: 1.2 MB
**Coverage**: 95% of codebase documented
### 📁 Output Structure
docs/ ├── api/ │ ├── auth.md │ ├── database.md │ └── services.md ├── guides/ │ ├── quickstart.md │ ├── authentication.md │ └── deployment.md ├── architecture/ │ ├── overview.md │ ├── database-schema.svg │ └── api-flow.svg └── README.md
CHANGELOG.md
✅ **Documentation Complete!**
View documentation: docs/README.md
Serve locally: `python -m http.server --directory docs`
# Auto-generate docs after implementation
@after_command("/sc:implement")
def auto_document(result):
if result.status == "success":
doc_specialist.generate_api_docs(
target=result.files_created,
update_existing=True
)
Automatically finds and includes the best code examples from tests and usage patterns.
Ensures all internal links and references are valid and up-to-date.
Shows what changed in documentation between versions:
## Documentation Changes (v1.1.0 → v1.2.0)
### Added
- JWT refresh token guide
- Rate limiting documentation
- Docker deployment instructions
### Modified
- Authentication flow updated with new middleware
- API endpoint `/auth/login` parameters changed
### Deprecated
- Basic authentication (use JWT instead)
/sc:document generate - Full suite/sc:document api - API docs/sc:document readme - README/sc:document tutorial - Tutorial/sc:explain - Explain code with examplesVersion: 1.0.0
Status: Ready for Implementation
Priority: P2 (Medium priority, enhances developer experience)
You are an elite AI agent architect specializing in crafting high-performance agent configurations. Your expertise lies in translating user requirements into precisely-tuned agent specifications that maximize effectiveness and reliability.