# SourceScribe
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](./website/docs/)
> An intelligent auto-documentation engine that generates **feature-based, process-oriented documentation** with extensive visual diagrams.
Powered by LLMs (Claude, OpenAI, Ollama) and designed for developers who want documentation that explains **how to USE** the system, not just browse source files.
**🎯 Different from other doc tools:** SourceScribe organizes docs by **features & workflows** with **10+ diagrams**, not by individual source files.
---
## 📑 Table of Contents
- [Key Features](#-key-features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Usage Examples](#-usage-examples)
- [Documentation Philosophy](#-documentation-philosophy)
- [Architecture](#️-architecture)
- [How It Works](#-how-it-works)
- [Example Output](#-example-output)
- [Docusaurus Integration](#-integration-with-docusaurus)
- [Development](#development)
- [Why SourceScribe?](#-why-sourcescribe)
- [Roadmap](#️-roadmap)
---
## ✨ Key Features
- 🎯 **Feature-Based Documentation**: Organizes by capabilities and workflows, not file structure
- 📊 **Diagram-Rich**: Generates 10+ Mermaid diagrams (sequence, flowchart, architecture, class)
- 🔄 **Process-Oriented**: Explains "How it Works" with visual workflows
- 🚀 **User-Centric**: Written for developers who want to USE the system
- 🔗 **GitHub Permalinks**: Automatically links to actual code with line-level precision
- ✨ **Auto-Sidebar Generation**: Automatically generates Docusaurus `sidebars.ts` - no manual config!
- 🤖 **Multi-LLM Support**: Claude (Anthropic), OpenAI (GPT-4), and Ollama
- 👁️ **Real-time Watching**: Monitors code changes and auto-regenerates docs
- 🌐 **Multi-language**: Supports Python, TypeScript, Java, Go, Rust, and more
- ⚙️ **Configurable**: Flexible YAML-based configuration with Pydantic models
- 🔄 **Cross-platform**: Works on macOS, Linux, and Windows
- 🚢 **GitHub Actions Ready**: Works seamlessly in any project's CI/CD pipeline
## Installation
```bash
# Clone the repository
git clone https://github.com/source-scribe/sourcescribe-core.git
cd sourcescribe-core
# Install dependencies
pip install -r requirements.txt
# Or install in development mode
pip install -e .
```
## Quick Start
### 1. Configure API Keys
Set up your LLM API keys as environment variables:
```bash
export ANTHROPIC_API_KEY="your-anthropic-key"
export OPENAI_API_KEY="your-openai-key"
# Ollama runs locally, no key needed
```
### 2. Initialize a Project
```bash
sourcescribe init /path/to/your/project
```
This creates a `.sourcescribe.yaml` configuration file.
### 3. Generate Documentation
```bash
# Generate feature-based documentation
sourcescribe generate .
# Specify output directory
sourcescribe generate . --output ./docs/api-reference
# Use specific LLM provider
sourcescribe generate . --provider anthropic --model claude-3-haiku-20240307
# Watch mode (auto-regenerate on changes)
sourcescribe watch .
```
### 4. View Your Documentation
SourceScribe generates a feature-based documentation structure:
```
docs/
├── README.md # Navigation hub
├── overview/
│ ├── index.md # Project overview
│ ├── architecture.md # System design + diagrams
│ └── technology-stack.md # Tech stack
├── getting-started/
│ ├── installation.md # Setup guide + flowchart
│ ├── quick-start.md # Tutorial + sequence diagram
│ └── configuration.md # Config options
├── features/
│ └── index.md # Feature documentation + diagrams
└── architecture/
└── components.md # Deep dive + multiple diagrams
```
## Configuration
Example `.sourcescribe.yaml`:
```yaml
# LLM Provider Configuration
llm:
provider: "anthropic" # anthropic, openai, or ollama
model: "claude-3-5-sonnet-20241022"
temperature: 0.3
max_tokens: 4000
# Repository Settings
repository:
path: "."
exclude_patterns:
- "*.pyc"
- "__pycache__"
- "node_modules"
- ".git"
include_patterns:
- "*.py"
- "*.js"
- "*.ts"
- "*.java"
- "*.go"
# Documentation Output
output:
path: "./docs/generated"
format: "markdown"
include_diagrams: true
diagram_format: "mermaid"
# Watch Mode Settings
watch:
enabled: true
debounce_seconds: 2.0
batch_changes: true
# Documentation Style
style:
include_examples: true
include_architecture: true
include_api_docs: true
verbosity: "detailed" # minimal, normal, detailed
```
## 📖 Usage Examples
### Generate Documentation with Anthropic Claude
```bash
# Using Claude 3 Haiku (fast and economical)
export ANTHROPIC_API_KEY="your-key-here"
sourcescribe generate . --provider anthropic --model claude-3-haiku-20240307
```
### Generate for Docusaurus Site
```bash
# Output directly to Docusaurus docs folder
sourcescribe generate . --output ./website/docs/api-reference
```
### Watch Mode with Custom Config
```bash
sourcescribe watch --config .sourcescribe.yaml
```
### Use Local Ollama (No API Key Required)
```bash
# Install Ollama from https://ollama.ai
ollama serve
ollama pull llama2
sourcescribe generate . --provider ollama --model llama2
```
## 📚 Documentation Philosophy
### Feature-Based, Not File-Based
SourceScribe generates documentation organized by **features and workflows**, not individual source files.
**Before (File-Based):**
```
❌ docs/files/sourcescribe_cli.md
❌ docs/files/sourcescribe_engine_generator.md
❌ docs/files/sourcescribe_api_anthropic_provider.md
... (100+ files)
```
**After (Feature-Based):**
```
✅ Overview → Architecture Overview → Technology Stack
✅ Getting Started → Installation → Quick Start → Configuration
✅ Features → Documentation Generation → LLM Integration
✅ Architecture → Component Architecture (deep dive)
```
### Diagram-First Approach
Every major section includes visual diagrams:
- **Sequence Diagrams**: Show workflows and interactions
- **Flowcharts**: Explain decision trees and processes
- **Architecture Diagrams**: Visualize system structure
- **Class Diagrams**: Document data models
## 🏗️ Architecture
SourceScribe consists of several key components:
- **Engine**: Core documentation generation with feature-based orchestration
- **Feature Generator**: Creates process-oriented docs with extensive diagrams
- **Watch**: File system monitoring and change detection
- **API**: LLM provider integrations (Anthropic, OpenAI, Ollama)
- **Config**: Pydantic-based configuration management
- **Diagram Generator**: Creates Mermaid.js visualizations
- **Utils**: Code analysis, parsing, and file handling
## 🔄 How It Works
```mermaid
flowchart TD
A[Analyze Codebase] --> B[Identify Features]
B --> C[Build Context]
C --> D{Generate Sections}
D --> E[Overview]
D --> F[Getting Started]
D --> G[Features]
D --> H[Architecture]
E --> I[Create Diagrams]
F --> I
G --> I
H --> I
I --> J[Output Markdown]
```
1. **Code Analysis**: Analyzes source files to extract structure, dependencies, and patterns
2. **Feature Identification**: Groups functionality by features/capabilities
3. **Context Building**: Builds rich context for each documentation section
4. **LLM Processing**: Generates process-oriented documentation with diagram prompts
5. **Diagram Generation**: Creates 10+ Mermaid.js diagrams throughout docs
6. **Section Organization**: Structures docs by user journey (Overview → Install → Features)
7. **Output**: Writes feature-based markdown with embedded diagrams
## 📸 Example Output
### Generated Documentation Structure
When you run `sourcescribe generate`, you get a complete documentation site:
```
api-reference/
├── README.md # 🏠 Navigation hub with quick links
│
├── overview/
│ ├── index.md # Project purpose, users, value props
│ ├── architecture.md # 📊 System design + arch diagram + sequence diagram
│ └── technology-stack.md # Languages, frameworks, tools
│
├── getting-started/
│ ├── installation.md # 📋 Prerequisites + installation flowchart
│ ├── quick-start.md # 🚀 Tutorial + "what happened" sequence diagram
│ └── configuration.md # ⚙️ All config options in tables
│
├── features/
│ └── index.md # 🎯 Feature docs with process diagrams
│
└── architecture/
└── components.md # 🏗️ Deep dive + multiple diagrams
```
### Diagram Examples
Every section includes rich visual diagrams:
**Quick Start (Sequence Diagram):**
```mermaid
sequenceDiagram
User->>SourceScribe: generate_documentation()
SourceScribe->>Analyzer: Analyze codebase
Analyzer->>LLM: Generate docs
LLM->>SourceScribe: Return documentation
SourceScribe->>User: Display results
```
**Installation (Flowchart):**
```mermaid
flowchart TD
Start([Start]) --> Check{Python 3.7+?}
Check -->|No| Install[Install Python]
Check -->|Yes| Clone[Clone Repository]
Install --> Clone
Clone --> Deps[Install Dependencies]
Deps --> Keys[Set API Keys]
Keys --> Config[Create Config]
Config --> Test[Test Installation]
Test --> End([Ready!])
```
**Architecture (Component Diagram):**
Shows the full system architecture with module dependencies and data flow.
## 🎨 Integration with Docusaurus
SourceScribe works seamlessly with Docusaurus and **automatically generates** the sidebar configuration!
```bash
# Generate docs for Docusaurus
sourcescribe generate . --output ./website/docs/api-reference
# Sidebar is auto-generated! Just build and start
cd website && npm start
```
### ✨ Auto-Generated Configuration
SourceScribe automatically configures Docusaurus based on your GitHub repository:
**1. Sidebar Generation** - Creates `sidebars.ts` matching your docs structure
**2. Config Update** - Updates `docusaurus.config.ts` with your GitHub org/repo
**What Gets Updated:**
```typescript
// docusaurus.config.ts
organizationName: 'Source-Scribe', // Auto-detected from GitHub URL
projectName: 'sourcescribe-core', // Auto-detected from GitHub URL
```
**Your Docusaurus sidebar will show:**
```
Documentation Home
├─ Overview
│ ├─ Project Overview
│ ├─ Architecture Overview
│ └─ Technology Stack
├─ Getting Started
│ ├─ Installation
│ ├─ Quick Start
│ └─ Configuration
├─ Features
│ └─ All Features
└─ Architecture
└─ Component Architecture
```
All Mermaid diagrams render beautifully with zoom support!
### 🚀 Use in Other Projects
SourceScribe works in **any project's GitHub Actions**! See [GITHUB_ACTIONS_SETUP.md](./GITHUB_ACTIONS_SETUP.md) for complete setup guide.
**Quick Example:**
```yaml
# .github/workflows/docs.yml
- name: Install SourceScribe
run: pip install sourcescribe
- name: Generate Documentation
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
sourcescribe generate . \
--output ./website/docs/api-reference \
--provider anthropic \
--model claude-3-haiku-20240307
```
**What Gets Auto-Generated:**
- ✅ Feature-based documentation structure
- ✅ 10+ Mermaid diagrams
- ✅ Docusaurus `sidebars.ts` (automatic!)
- ✅ Docusaurus config updated (organizationName, projectName)
- ✅ GitHub permalinks to actual code
- ✅ Navigation README
### GitHub Pages Deployment
To deploy your documentation to GitHub Pages:
1. **Enable GitHub Pages** in your repository settings:
- Go to Settings → Pages
- Source: Deploy from a branch
- Branch: `gh-pages` / `(root)`
2. **Repository Requirements**:
- ✅ **Public repositories**: GitHub Pages is available by default
- ⚠️ **Private repositories**: Requires GitHub Pro, Team, or Enterprise plan
> **Note:** If your repository is private and you're on the Free plan, you'll need to either:
> - Make your repository public, OR
> - Upgrade to GitHub Pro/Team/Enterprise to enable Pages for private repos
3. **Automatic Deployment**:
- Once enabled, the `.github/workflows/build-docs.yml` workflow will automatically deploy on every push to `main`
- Your site will be available at: `https://[username].github.io/[repo-name]/`
## Development
```bash
# Install development dependencies
pip install -r requirements-dev.txt
# Run tests
pytest tests/
# Format code
black sourcescribe/
# Type checking
mypy sourcescribe/
# Linting
ruff check sourcescribe/
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
MIT License - see LICENSE file for details.
## 🌟 Why SourceScribe?
### vs Manual Documentation
- ✅ **Always up-to-date**: Regenerate docs with one command
- ✅ **Consistent**: LLM ensures uniform style and structure
- ✅ **Comprehensive**: Never miss documenting a feature
- ✅ **Visual**: Auto-generates diagrams you'd never draw manually
### vs File-Based Tools (JSDoc, Sphinx, etc.)
- ✅ **Feature-focused**: Organized by what users want to do
- ✅ **Process-oriented**: Explains workflows, not just APIs
- ✅ **User-centric**: Written for developers using the system
- ✅ **Rich diagrams**: 10+ visual explanations per project
### vs README-only Projects
- ✅ **Structured**: Clear sections with progressive disclosure
- ✅ **Complete**: Installation, features, architecture all covered
- ✅ **Navigable**: Easy to find specific information
- ✅ **Scalable**: Works for projects of any size
## 🚦 Supported LLM Providers
| Provider | Models | API Key Required | Cost |
|----------|--------|------------------|------|
| **Anthropic** | Claude 3 Haiku, Sonnet, Opus | ✅ Yes | $$ |
| **OpenAI** | GPT-4, GPT-4 Turbo | ✅ Yes | $$$ |
| **Ollama** | Llama 2, Mistral, CodeLlama | ❌ No (local) | Free |
**Recommended:** Use **Claude 3 Haiku** for best balance of speed, quality, and cost.
## 🗺️ Roadmap
- [ ] Support for more diagram types (state, entity-relationship)
- [ ] Custom feature templates
- [ ] Multi-language documentation output
- [ ] GitHub Actions integration
- [ ] VS Code extension
- [ ] API documentation from OpenAPI specs
- [ ] Incremental regeneration (only changed features)
## Acknowledgments
- Inspired by [CodeWiki](https://github.com/FSoft-AI4Code/CodeWiki)
- Research paper: [arXiv:2510.24428v2](https://arxiv.org/html/2510.24428v2)
- Documentation philosophy inspired by [Devin.ai](https://devin.ai) and [Stripe Docs](https://stripe.com/docs)
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/sourcescribe",
"name": "sourcescribe",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "documentation, llm, code-analysis, mermaid, auto-doc",
"author": "SourceScribe Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/2d/5c/6794a2d24c6694fe6165542af69d4ba8f663668e81c53c75a7086b36aca5/sourcescribe-1.3.1.tar.gz",
"platform": null,
"description": "# SourceScribe\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](./website/docs/)\n\n> An intelligent auto-documentation engine that generates **feature-based, process-oriented documentation** with extensive visual diagrams.\n\nPowered by LLMs (Claude, OpenAI, Ollama) and designed for developers who want documentation that explains **how to USE** the system, not just browse source files.\n\n**\ud83c\udfaf Different from other doc tools:** SourceScribe organizes docs by **features & workflows** with **10+ diagrams**, not by individual source files.\n\n---\n\n## \ud83d\udcd1 Table of Contents\n\n- [Key Features](#-key-features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Configuration](#configuration)\n- [Usage Examples](#-usage-examples)\n- [Documentation Philosophy](#-documentation-philosophy)\n- [Architecture](#\ufe0f-architecture)\n- [How It Works](#-how-it-works)\n- [Example Output](#-example-output)\n- [Docusaurus Integration](#-integration-with-docusaurus)\n- [Development](#development)\n- [Why SourceScribe?](#-why-sourcescribe)\n- [Roadmap](#\ufe0f-roadmap)\n\n---\n\n## \u2728 Key Features\n\n- \ud83c\udfaf **Feature-Based Documentation**: Organizes by capabilities and workflows, not file structure\n- \ud83d\udcca **Diagram-Rich**: Generates 10+ Mermaid diagrams (sequence, flowchart, architecture, class)\n- \ud83d\udd04 **Process-Oriented**: Explains \"How it Works\" with visual workflows\n- \ud83d\ude80 **User-Centric**: Written for developers who want to USE the system\n- \ud83d\udd17 **GitHub Permalinks**: Automatically links to actual code with line-level precision\n- \u2728 **Auto-Sidebar Generation**: Automatically generates Docusaurus `sidebars.ts` - no manual config!\n- \ud83e\udd16 **Multi-LLM Support**: Claude (Anthropic), OpenAI (GPT-4), and Ollama\n- \ud83d\udc41\ufe0f **Real-time Watching**: Monitors code changes and auto-regenerates docs\n- \ud83c\udf10 **Multi-language**: Supports Python, TypeScript, Java, Go, Rust, and more\n- \u2699\ufe0f **Configurable**: Flexible YAML-based configuration with Pydantic models\n- \ud83d\udd04 **Cross-platform**: Works on macOS, Linux, and Windows\n- \ud83d\udea2 **GitHub Actions Ready**: Works seamlessly in any project's CI/CD pipeline\n\n## Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/source-scribe/sourcescribe-core.git\ncd sourcescribe-core\n\n# Install dependencies\npip install -r requirements.txt\n\n# Or install in development mode\npip install -e .\n```\n\n## Quick Start\n\n### 1. Configure API Keys\n\nSet up your LLM API keys as environment variables:\n\n```bash\nexport ANTHROPIC_API_KEY=\"your-anthropic-key\"\nexport OPENAI_API_KEY=\"your-openai-key\"\n# Ollama runs locally, no key needed\n```\n\n### 2. Initialize a Project\n\n```bash\nsourcescribe init /path/to/your/project\n```\n\nThis creates a `.sourcescribe.yaml` configuration file.\n\n### 3. Generate Documentation\n\n```bash\n# Generate feature-based documentation\nsourcescribe generate .\n\n# Specify output directory\nsourcescribe generate . --output ./docs/api-reference\n\n# Use specific LLM provider\nsourcescribe generate . --provider anthropic --model claude-3-haiku-20240307\n\n# Watch mode (auto-regenerate on changes)\nsourcescribe watch .\n```\n\n### 4. View Your Documentation\n\nSourceScribe generates a feature-based documentation structure:\n\n```\ndocs/\n\u251c\u2500\u2500 README.md # Navigation hub\n\u251c\u2500\u2500 overview/\n\u2502 \u251c\u2500\u2500 index.md # Project overview\n\u2502 \u251c\u2500\u2500 architecture.md # System design + diagrams\n\u2502 \u2514\u2500\u2500 technology-stack.md # Tech stack\n\u251c\u2500\u2500 getting-started/\n\u2502 \u251c\u2500\u2500 installation.md # Setup guide + flowchart\n\u2502 \u251c\u2500\u2500 quick-start.md # Tutorial + sequence diagram\n\u2502 \u2514\u2500\u2500 configuration.md # Config options\n\u251c\u2500\u2500 features/\n\u2502 \u2514\u2500\u2500 index.md # Feature documentation + diagrams\n\u2514\u2500\u2500 architecture/\n \u2514\u2500\u2500 components.md # Deep dive + multiple diagrams\n```\n\n## Configuration\n\nExample `.sourcescribe.yaml`:\n\n```yaml\n# LLM Provider Configuration\nllm:\n provider: \"anthropic\" # anthropic, openai, or ollama\n model: \"claude-3-5-sonnet-20241022\"\n temperature: 0.3\n max_tokens: 4000\n\n# Repository Settings\nrepository:\n path: \".\"\n exclude_patterns:\n - \"*.pyc\"\n - \"__pycache__\"\n - \"node_modules\"\n - \".git\"\n include_patterns:\n - \"*.py\"\n - \"*.js\"\n - \"*.ts\"\n - \"*.java\"\n - \"*.go\"\n\n# Documentation Output\noutput:\n path: \"./docs/generated\"\n format: \"markdown\"\n include_diagrams: true\n diagram_format: \"mermaid\"\n\n# Watch Mode Settings\nwatch:\n enabled: true\n debounce_seconds: 2.0\n batch_changes: true\n\n# Documentation Style\nstyle:\n include_examples: true\n include_architecture: true\n include_api_docs: true\n verbosity: \"detailed\" # minimal, normal, detailed\n```\n\n## \ud83d\udcd6 Usage Examples\n\n### Generate Documentation with Anthropic Claude\n\n```bash\n# Using Claude 3 Haiku (fast and economical)\nexport ANTHROPIC_API_KEY=\"your-key-here\"\nsourcescribe generate . --provider anthropic --model claude-3-haiku-20240307\n```\n\n### Generate for Docusaurus Site\n\n```bash\n# Output directly to Docusaurus docs folder\nsourcescribe generate . --output ./website/docs/api-reference\n```\n\n### Watch Mode with Custom Config\n\n```bash\nsourcescribe watch --config .sourcescribe.yaml\n```\n\n### Use Local Ollama (No API Key Required)\n\n```bash\n# Install Ollama from https://ollama.ai\nollama serve\nollama pull llama2\n\nsourcescribe generate . --provider ollama --model llama2\n```\n\n## \ud83d\udcda Documentation Philosophy\n\n### Feature-Based, Not File-Based\n\nSourceScribe generates documentation organized by **features and workflows**, not individual source files.\n\n**Before (File-Based):**\n```\n\u274c docs/files/sourcescribe_cli.md\n\u274c docs/files/sourcescribe_engine_generator.md\n\u274c docs/files/sourcescribe_api_anthropic_provider.md\n... (100+ files)\n```\n\n**After (Feature-Based):**\n```\n\u2705 Overview \u2192 Architecture Overview \u2192 Technology Stack\n\u2705 Getting Started \u2192 Installation \u2192 Quick Start \u2192 Configuration\n\u2705 Features \u2192 Documentation Generation \u2192 LLM Integration\n\u2705 Architecture \u2192 Component Architecture (deep dive)\n```\n\n### Diagram-First Approach\n\nEvery major section includes visual diagrams:\n- **Sequence Diagrams**: Show workflows and interactions\n- **Flowcharts**: Explain decision trees and processes\n- **Architecture Diagrams**: Visualize system structure\n- **Class Diagrams**: Document data models\n\n## \ud83c\udfd7\ufe0f Architecture\n\nSourceScribe consists of several key components:\n\n- **Engine**: Core documentation generation with feature-based orchestration\n- **Feature Generator**: Creates process-oriented docs with extensive diagrams\n- **Watch**: File system monitoring and change detection\n- **API**: LLM provider integrations (Anthropic, OpenAI, Ollama)\n- **Config**: Pydantic-based configuration management\n- **Diagram Generator**: Creates Mermaid.js visualizations\n- **Utils**: Code analysis, parsing, and file handling\n\n## \ud83d\udd04 How It Works\n\n```mermaid\nflowchart TD\n A[Analyze Codebase] --> B[Identify Features]\n B --> C[Build Context]\n C --> D{Generate Sections}\n D --> E[Overview]\n D --> F[Getting Started]\n D --> G[Features]\n D --> H[Architecture]\n E --> I[Create Diagrams]\n F --> I\n G --> I\n H --> I\n I --> J[Output Markdown]\n```\n\n1. **Code Analysis**: Analyzes source files to extract structure, dependencies, and patterns\n2. **Feature Identification**: Groups functionality by features/capabilities\n3. **Context Building**: Builds rich context for each documentation section\n4. **LLM Processing**: Generates process-oriented documentation with diagram prompts\n5. **Diagram Generation**: Creates 10+ Mermaid.js diagrams throughout docs\n6. **Section Organization**: Structures docs by user journey (Overview \u2192 Install \u2192 Features)\n7. **Output**: Writes feature-based markdown with embedded diagrams\n\n## \ud83d\udcf8 Example Output\n\n### Generated Documentation Structure\n\nWhen you run `sourcescribe generate`, you get a complete documentation site:\n\n```\napi-reference/\n\u251c\u2500\u2500 README.md # \ud83c\udfe0 Navigation hub with quick links\n\u2502\n\u251c\u2500\u2500 overview/\n\u2502 \u251c\u2500\u2500 index.md # Project purpose, users, value props\n\u2502 \u251c\u2500\u2500 architecture.md # \ud83d\udcca System design + arch diagram + sequence diagram \n\u2502 \u2514\u2500\u2500 technology-stack.md # Languages, frameworks, tools\n\u2502\n\u251c\u2500\u2500 getting-started/\n\u2502 \u251c\u2500\u2500 installation.md # \ud83d\udccb Prerequisites + installation flowchart\n\u2502 \u251c\u2500\u2500 quick-start.md # \ud83d\ude80 Tutorial + \"what happened\" sequence diagram\n\u2502 \u2514\u2500\u2500 configuration.md # \u2699\ufe0f All config options in tables\n\u2502\n\u251c\u2500\u2500 features/\n\u2502 \u2514\u2500\u2500 index.md # \ud83c\udfaf Feature docs with process diagrams\n\u2502\n\u2514\u2500\u2500 architecture/\n \u2514\u2500\u2500 components.md # \ud83c\udfd7\ufe0f Deep dive + multiple diagrams\n```\n\n### Diagram Examples\n\nEvery section includes rich visual diagrams:\n\n**Quick Start (Sequence Diagram):**\n```mermaid\nsequenceDiagram\n User->>SourceScribe: generate_documentation()\n SourceScribe->>Analyzer: Analyze codebase\n Analyzer->>LLM: Generate docs\n LLM->>SourceScribe: Return documentation\n SourceScribe->>User: Display results\n```\n\n**Installation (Flowchart):**\n```mermaid\nflowchart TD\n Start([Start]) --> Check{Python 3.7+?}\n Check -->|No| Install[Install Python]\n Check -->|Yes| Clone[Clone Repository]\n Install --> Clone\n Clone --> Deps[Install Dependencies]\n Deps --> Keys[Set API Keys]\n Keys --> Config[Create Config]\n Config --> Test[Test Installation]\n Test --> End([Ready!])\n```\n\n**Architecture (Component Diagram):**\nShows the full system architecture with module dependencies and data flow.\n\n## \ud83c\udfa8 Integration with Docusaurus\n\nSourceScribe works seamlessly with Docusaurus and **automatically generates** the sidebar configuration!\n\n```bash\n# Generate docs for Docusaurus\nsourcescribe generate . --output ./website/docs/api-reference\n\n# Sidebar is auto-generated! Just build and start\ncd website && npm start\n```\n\n### \u2728 Auto-Generated Configuration\n\nSourceScribe automatically configures Docusaurus based on your GitHub repository:\n\n**1. Sidebar Generation** - Creates `sidebars.ts` matching your docs structure\n**2. Config Update** - Updates `docusaurus.config.ts` with your GitHub org/repo\n\n**What Gets Updated:**\n```typescript\n// docusaurus.config.ts\norganizationName: 'Source-Scribe', // Auto-detected from GitHub URL\nprojectName: 'sourcescribe-core', // Auto-detected from GitHub URL\n```\n\n**Your Docusaurus sidebar will show:**\n```\nDocumentation Home\n\u251c\u2500 Overview\n\u2502 \u251c\u2500 Project Overview \n\u2502 \u251c\u2500 Architecture Overview\n\u2502 \u2514\u2500 Technology Stack\n\u251c\u2500 Getting Started\n\u2502 \u251c\u2500 Installation\n\u2502 \u251c\u2500 Quick Start\n\u2502 \u2514\u2500 Configuration\n\u251c\u2500 Features\n\u2502 \u2514\u2500 All Features\n\u2514\u2500 Architecture\n \u2514\u2500 Component Architecture\n```\n\nAll Mermaid diagrams render beautifully with zoom support!\n\n### \ud83d\ude80 Use in Other Projects\n\nSourceScribe works in **any project's GitHub Actions**! See [GITHUB_ACTIONS_SETUP.md](./GITHUB_ACTIONS_SETUP.md) for complete setup guide.\n\n**Quick Example:**\n```yaml\n# .github/workflows/docs.yml\n- name: Install SourceScribe\n run: pip install sourcescribe\n\n- name: Generate Documentation\n env:\n ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}\n run: |\n sourcescribe generate . \\\n --output ./website/docs/api-reference \\\n --provider anthropic \\\n --model claude-3-haiku-20240307\n```\n\n**What Gets Auto-Generated:**\n- \u2705 Feature-based documentation structure\n- \u2705 10+ Mermaid diagrams\n- \u2705 Docusaurus `sidebars.ts` (automatic!)\n- \u2705 Docusaurus config updated (organizationName, projectName)\n- \u2705 GitHub permalinks to actual code\n- \u2705 Navigation README\n\n### GitHub Pages Deployment\n\nTo deploy your documentation to GitHub Pages:\n\n1. **Enable GitHub Pages** in your repository settings:\n - Go to Settings \u2192 Pages\n - Source: Deploy from a branch\n - Branch: `gh-pages` / `(root)`\n\n2. **Repository Requirements**:\n - \u2705 **Public repositories**: GitHub Pages is available by default\n - \u26a0\ufe0f **Private repositories**: Requires GitHub Pro, Team, or Enterprise plan\n \n > **Note:** If your repository is private and you're on the Free plan, you'll need to either:\n > - Make your repository public, OR\n > - Upgrade to GitHub Pro/Team/Enterprise to enable Pages for private repos\n\n3. **Automatic Deployment**:\n - Once enabled, the `.github/workflows/build-docs.yml` workflow will automatically deploy on every push to `main`\n - Your site will be available at: `https://[username].github.io/[repo-name]/`\n\n## Development\n\n```bash\n# Install development dependencies\npip install -r requirements-dev.txt\n\n# Run tests\npytest tests/\n\n# Format code\nblack sourcescribe/\n\n# Type checking\nmypy sourcescribe/\n\n# Linting\nruff check sourcescribe/\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## \ud83c\udf1f Why SourceScribe?\n\n### vs Manual Documentation\n- \u2705 **Always up-to-date**: Regenerate docs with one command\n- \u2705 **Consistent**: LLM ensures uniform style and structure\n- \u2705 **Comprehensive**: Never miss documenting a feature\n- \u2705 **Visual**: Auto-generates diagrams you'd never draw manually\n\n### vs File-Based Tools (JSDoc, Sphinx, etc.)\n- \u2705 **Feature-focused**: Organized by what users want to do\n- \u2705 **Process-oriented**: Explains workflows, not just APIs\n- \u2705 **User-centric**: Written for developers using the system\n- \u2705 **Rich diagrams**: 10+ visual explanations per project\n\n### vs README-only Projects\n- \u2705 **Structured**: Clear sections with progressive disclosure\n- \u2705 **Complete**: Installation, features, architecture all covered\n- \u2705 **Navigable**: Easy to find specific information\n- \u2705 **Scalable**: Works for projects of any size\n\n## \ud83d\udea6 Supported LLM Providers\n\n| Provider | Models | API Key Required | Cost |\n|----------|--------|------------------|------|\n| **Anthropic** | Claude 3 Haiku, Sonnet, Opus | \u2705 Yes | $$ |\n| **OpenAI** | GPT-4, GPT-4 Turbo | \u2705 Yes | $$$ |\n| **Ollama** | Llama 2, Mistral, CodeLlama | \u274c No (local) | Free |\n\n**Recommended:** Use **Claude 3 Haiku** for best balance of speed, quality, and cost.\n\n## \ud83d\uddfa\ufe0f Roadmap\n\n- [ ] Support for more diagram types (state, entity-relationship)\n- [ ] Custom feature templates\n- [ ] Multi-language documentation output\n- [ ] GitHub Actions integration\n- [ ] VS Code extension\n- [ ] API documentation from OpenAPI specs\n- [ ] Incremental regeneration (only changed features)\n\n## Acknowledgments\n\n- Inspired by [CodeWiki](https://github.com/FSoft-AI4Code/CodeWiki)\n- Research paper: [arXiv:2510.24428v2](https://arxiv.org/html/2510.24428v2)\n- Documentation philosophy inspired by [Devin.ai](https://devin.ai) and [Stripe Docs](https://stripe.com/docs)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Auto-documentation engine using LLMs to generate insightful documentation with architecture diagrams",
"version": "1.3.1",
"project_urls": {
"Documentation": "http://sourcescribe.ai",
"Homepage": "https://github.com/Source-Scribe/sourcescribe-core",
"Repository": "https://github.com/Source-Scribe/sourcescribe-core"
},
"split_keywords": [
"documentation",
" llm",
" code-analysis",
" mermaid",
" auto-doc"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d46e38f782d919336e4f3ad887e946f3c714936f2d718b3b5df3191eb6c7b4c3",
"md5": "b519ec7a6f179b7ff081517dcea3db5d",
"sha256": "a4feff6de1eccb33b63978c55bf9ec2f47e4a829fd8b019b31472bc4021e18b3"
},
"downloads": -1,
"filename": "sourcescribe-1.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b519ec7a6f179b7ff081517dcea3db5d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 53342,
"upload_time": "2025-11-10T02:11:28",
"upload_time_iso_8601": "2025-11-10T02:11:28.677846Z",
"url": "https://files.pythonhosted.org/packages/d4/6e/38f782d919336e4f3ad887e946f3c714936f2d718b3b5df3191eb6c7b4c3/sourcescribe-1.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2d5c6794a2d24c6694fe6165542af69d4ba8f663668e81c53c75a7086b36aca5",
"md5": "c578599266b394cdeb51d39d170f9c58",
"sha256": "f5df1ad238cae6d28cabdd5ee820eed0d254e284c55500c507480a1a519e33d5"
},
"downloads": -1,
"filename": "sourcescribe-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "c578599266b394cdeb51d39d170f9c58",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 349297,
"upload_time": "2025-11-10T02:11:29",
"upload_time_iso_8601": "2025-11-10T02:11:29.786427Z",
"url": "https://files.pythonhosted.org/packages/2d/5c/6794a2d24c6694fe6165542af69d4ba8f663668e81c53c75a7086b36aca5/sourcescribe-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-10 02:11:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "sourcescribe",
"github_not_found": true,
"lcname": "sourcescribe"
}
JSON
