Initial commit
This commit is contained in:
Zhongwei Li
222
skills/documentation-wizard/README.md
Normal file
222
skills/documentation-wizard/README.md
Normal file
@@ -0,0 +1,222 @@
|
||||
# Documentation Wizard
|
||||
|
||||
**Living Documentation Expert - Always in Sync**
|
||||
|
||||
Documentation Wizard keeps your documentation perfectly synchronized with code, decisions, and learnings. It integrates with Oracle, Summoner, and Style Master to create comprehensive, up-to-date documentation automatically.
|
||||
|
||||
## What It Does
|
||||
|
||||
### 📝 Auto-Generate Documentation
|
||||
- README files from code + Oracle knowledge
|
||||
- API documentation from code comments
|
||||
- Architecture Decision Records (ADRs) from decisions
|
||||
- Onboarding guides from Oracle sessions
|
||||
- Changelogs from git history + Oracle
|
||||
|
||||
### 🔄 Continuous Synchronization
|
||||
- Detects code changes and updates docs
|
||||
- Pulls patterns from Oracle knowledge
|
||||
- Extracts decisions from Summoner MCDs
|
||||
- Syncs Style Master style guides
|
||||
- Validates examples still work
|
||||
|
||||
### ✅ Documentation Validation
|
||||
- Detects stale documentation
|
||||
- Finds broken links
|
||||
- Validates code examples
|
||||
- Identifies missing documentation
|
||||
- Checks for inconsistencies
|
||||
|
||||
### 🔗 Integration Powerhouse
|
||||
- **Oracle**: Leverage learnings and decisions
|
||||
- **Summoner**: Extract design docs from MCDs
|
||||
- **Style Master**: Sync style guide documentation
|
||||
- **Git**: Track evolution and changes
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Generate initial documentation
|
||||
python .claude/skills/documentation-wizard/scripts/generate_docs.py
|
||||
|
||||
# Validate documentation
|
||||
python .claude/skills/documentation-wizard/scripts/validate_docs.py
|
||||
|
||||
# Sync from Oracle knowledge
|
||||
python .claude/skills/documentation-wizard/scripts/sync_docs.py --source oracle
|
||||
|
||||
# Generate changelog
|
||||
python .claude/skills/documentation-wizard/scripts/generate_changelog.py
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
### 1. Initial Documentation Setup
|
||||
```
|
||||
Use the documentation wizard to set up documentation for our project.
|
||||
|
||||
[Analyzes codebase]
|
||||
[Loads Oracle knowledge]
|
||||
[Generates README, API docs, contributing guide]
|
||||
[Creates documentation structure]
|
||||
```
|
||||
|
||||
### 2. Keep Docs in Sync
|
||||
```
|
||||
Update documentation based on recent changes.
|
||||
|
||||
[Checks git diff]
|
||||
[Identifies affected docs]
|
||||
[Updates API documentation]
|
||||
[Generates changelog entry]
|
||||
```
|
||||
|
||||
### 3. Create ADRs from Decisions
|
||||
```
|
||||
Create ADR for our decision to use PostgreSQL over MongoDB.
|
||||
|
||||
[Loads Oracle decision entry]
|
||||
[Reads Summoner MCD rationale]
|
||||
[Generates ADR-015-database-choice.md]
|
||||
[Links to Oracle and Summoner references]
|
||||
```
|
||||
|
||||
## Documentation Types
|
||||
|
||||
### Generated Documentation
|
||||
|
||||
| Type | Source | Output |
|
||||
|------|--------|--------|
|
||||
| **README** | Code + Oracle + Summoner | README.md |
|
||||
| **API Docs** | JSDoc/TypeDoc comments | docs/api/ |
|
||||
| **ADRs** | Oracle decisions + Summoner MCDs | docs/adr/ |
|
||||
| **Style Guide** | Style Master | docs/STYLEGUIDE.md |
|
||||
| **Onboarding** | Oracle sessions | docs/ONBOARDING.md |
|
||||
| **Changelog** | Git + Oracle | CHANGELOG.md |
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### With Oracle 🧠
|
||||
|
||||
**Oracle knows**: "Use factory pattern for DB connections"
|
||||
|
||||
**Docs generated**:
|
||||
```markdown
|
||||
## Database Connections
|
||||
|
||||
All database connections use the factory pattern:
|
||||
\`\`\`typescript
|
||||
const db = DatabaseFactory.create('postgres');
|
||||
\`\`\`
|
||||
This ensures proper connection pooling. See Oracle entry #42.
|
||||
```
|
||||
|
||||
### With Summoner 🧙
|
||||
|
||||
**Summoner MCD**: Microservices migration decision
|
||||
|
||||
**ADR generated**:
|
||||
```markdown
|
||||
# ADR-023: Migrate to Microservices Architecture
|
||||
|
||||
Context: From Summoner Mission "Microservices Migration"
|
||||
Decision: Extract auth service first, then user service
|
||||
Rationale: [From Summoner MCD]
|
||||
```
|
||||
|
||||
### With Style Master 🎨
|
||||
|
||||
**Style Master style guide**: Design tokens
|
||||
|
||||
**Docs synced**:
|
||||
```markdown
|
||||
# Theme Customization
|
||||
|
||||
Override design tokens in your CSS:
|
||||
\`\`\`css
|
||||
:root {
|
||||
--color-primary: #your-color;
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
See [Style Guide](./STYLEGUIDE.md) for all tokens.
|
||||
```
|
||||
|
||||
## Scripts Reference
|
||||
|
||||
### generate_docs.py
|
||||
Generates initial documentation from code and knowledge.
|
||||
|
||||
**Options**:
|
||||
- `--type readme|api|adr|onboarding|all`
|
||||
- `--output docs/`
|
||||
- `--include-oracle` (include Oracle knowledge)
|
||||
|
||||
### validate_docs.py
|
||||
Validates documentation for staleness and issues.
|
||||
|
||||
**Checks**:
|
||||
- Stale documentation
|
||||
- Broken links
|
||||
- Invalid examples
|
||||
- Missing documentation
|
||||
|
||||
### sync_docs.py
|
||||
Synchronizes documentation from various sources.
|
||||
|
||||
**Sources**:
|
||||
- `--source oracle` (Oracle knowledge)
|
||||
- `--source summoner` (Summoner MCDs)
|
||||
- `--source style-master` (Style guides)
|
||||
- `--source code` (Code comments)
|
||||
|
||||
### generate_changelog.py
|
||||
Generates changelog from git history and Oracle.
|
||||
|
||||
**Format**: Semantic (Added/Changed/Fixed/Deprecated/Removed)
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Document WHY, Not Just WHAT
|
||||
Use Oracle to capture the reasoning behind decisions.
|
||||
|
||||
### 2. Keep Examples Executable
|
||||
All code examples should be tested and copy-pasteable.
|
||||
|
||||
### 3. Link Everything
|
||||
Connect documentation to Oracle, Summoner, code, and external resources.
|
||||
|
||||
### 4. Automate Updates
|
||||
Set up hooks to update docs on code changes.
|
||||
|
||||
### 5. Validate Regularly
|
||||
Run validation as part of CI/CD.
|
||||
|
||||
## Workflow
|
||||
|
||||
```bash
|
||||
# Daily: After development session
|
||||
python .claude/skills/documentation-wizard/scripts/generate_docs.py --type api
|
||||
python .claude/skills/documentation-wizard/scripts/validate_docs.py
|
||||
|
||||
# Weekly: Comprehensive sync
|
||||
python .claude/skills/documentation-wizard/scripts/sync_docs.py --source all
|
||||
python .claude/skills/documentation-wizard/scripts/generate_changelog.py
|
||||
|
||||
# Before release: Full documentation review
|
||||
python .claude/skills/documentation-wizard/scripts/validate_docs.py --strict
|
||||
```
|
||||
|
||||
## Templates Available
|
||||
|
||||
- **README**: Project and package READMEs
|
||||
- **ADR**: Architecture Decision Records
|
||||
- **API**: API documentation
|
||||
- **Onboarding**: New developer guides
|
||||
- **Contributing**: Contribution guidelines
|
||||
|
||||
See `References/` directory for all templates.
|
||||
|
||||
---
|
||||
|
||||
**Documentation Wizard v1.0** - Documentation that stays alive
|
||||
Reference in New Issue
Block a user