Skip to content

Commit 42fd2db

Browse files
elijahrclaude
elijahr
and
claude
committed
feat: add MkDocs documentation and GitHub Pages deployment
- Create comprehensive documentation structure with MkDocs Material theme - Add getting started guides (installation, setup, quickstart) - Add user guide pages (workflows, MCP tools, CLI) - Add configuration documentation with examples - Generate API reference for all modules using mkdocstrings - Migrate technical documentation to docs/technical/ - Create architecture overview page - Add GitHub Actions workflow for automated deployment with mike - Configure versioned documentation support Content includes: - Home page with quick links and architecture diagram - Complete MCP tool reference (15 tools across 4 categories) - Workflow examples (library management, pattern generation, sample discovery) - CLI command reference - Configuration system documentation - Python API reference (7 modules) - Technical implementation details (9 pages) Deployment: - GitHub Actions deploys to GitHub Pages on push to main - Mike for version management - Auto-generates from Python docstrings 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent a52ef99 commit 42fd2db

26 files changed

Lines changed: 1021 additions & 0 deletions

‎.github/workflows/docs.yml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: write
11+
12+
jobs:
13+
deploy:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- uses: actions/checkout@v4
17+
with:
18+
fetch-depth: 0 # Full history for mike versioning
19+
20+
- name: Set up Python
21+
uses: actions/setup-python@v5
22+
with:
23+
python-version: '3.12'
24+
25+
- name: Install dependencies
26+
run: |
27+
pip install -e ".[docs]"
28+
29+
- name: Configure Git
30+
run: |
31+
git config user.name "github-actions[bot]"
32+
git config user.email "github-actions[bot]@users.noreply.github.com"
33+
34+
- name: Deploy with mike
35+
run: |
36+
mike deploy --push --update-aliases latest
37+
38+
- name: Set default version
39+
run: |
40+
mike set-default --push latest

‎docs/api/analyzers.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Analyzers API Reference
2+
3+
The `audiomancer.analyzers` module provides audio analysis functionality.
4+
5+
## Overview
6+
7+
::: audiomancer.analyzers
8+
options:
9+
show_root_heading: true
10+
show_source: false
11+
members: true
12+
13+
## Basic Metadata
14+
15+
::: audiomancer.analyzers.basic
16+
options:
17+
show_root_heading: true
18+
show_source: true
19+
20+
## Spectral Features
21+
22+
::: audiomancer.analyzers.spectral
23+
options:
24+
show_root_heading: true
25+
show_source: true
26+
27+
## Rhythm Features
28+
29+
::: audiomancer.analyzers.rhythm
30+
options:
31+
show_root_heading: true
32+
show_source: true
33+
34+
## Audio Embeddings
35+
36+
::: audiomancer.analyzers.embeddings
37+
options:
38+
show_root_heading: true
39+
show_source: true

‎docs/api/converters.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Converters API Reference
2+
3+
The `audiomancer.converters` module provides format conversion functionality.
4+
5+
## Overview
6+
7+
::: audiomancer.converters
8+
options:
9+
show_root_heading: true
10+
show_source: false
11+
members: true

‎docs/api/generators.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Generators API Reference
2+
3+
The `audiomancer.generators` module provides pattern generation and synth evolution functionality.
4+
5+
## Overview
6+
7+
::: audiomancer.generators
8+
options:
9+
show_root_heading: true
10+
show_source: false
11+
members: true

‎docs/api/index.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# API Reference
2+
3+
Audiomancer provides a Python API for audio analysis, pattern generation, and sample library management.
4+
5+
## Module Overview
6+
7+
- [audiomancer.analyzers](analyzers.md) - Audio analysis (spectral, rhythm, embeddings)
8+
- [audiomancer.converters](converters.md) - Format conversion (MIDI, SuperCollider, TidalCycles)
9+
- [audiomancer.generators](generators.md) - Pattern generation (drums, melody, bass)
10+
- [audiomancer.library](library.md) - Sample library management
11+
- [audiomancer.storage](storage.md) - Database and vector storage
12+
- [audiomancer.templates](templates.md) - Project templates
13+
14+
## Installation
15+
16+
```bash
17+
pip install audiomancer
18+
```
19+
20+
## Quick Example
21+
22+
```python
23+
from audiomancer.analyzers import extract_spectral_features
24+
from audiomancer.generators import generate_drums
25+
import librosa
26+
27+
# Analyze audio
28+
audio, sr = librosa.load("kick.wav")
29+
features = extract_spectral_features(audio, sr)
30+
31+
# Generate pattern
32+
drums = generate_drums(style="techno", bpm=130, bars=4)
33+
print(drums.tidal_code)
34+
```
35+
36+
## Documentation Conventions
37+
38+
- **Parameters:** Type-annotated function parameters
39+
- **Returns:** Return value type and description
40+
- **Raises:** Exceptions that may be raised
41+
- **Examples:** Usage examples in docstrings
42+
43+
## Next Steps
44+
45+
Browse the module documentation:
46+
47+
- [Analyzers API](analyzers.md)
48+
- [Generators API](generators.md)
49+
- [Library API](library.md)

‎docs/api/library.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Library API Reference
2+
3+
The `audiomancer.library` module provides sample library management functionality.
4+
5+
## Overview
6+
7+
::: audiomancer.library
8+
options:
9+
show_root_heading: true
10+
show_source: false
11+
members: true
12+
13+
## Library Manager
14+
15+
::: audiomancer.library.manager
16+
options:
17+
show_root_heading: true
18+
show_source: true
19+
20+
## Scanner
21+
22+
::: audiomancer.library.scanner
23+
options:
24+
show_root_heading: true
25+
show_source: true

‎docs/api/storage.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Storage API Reference
2+
3+
The `audiomancer.storage` module provides database and vector storage functionality.
4+
5+
## Overview
6+
7+
::: audiomancer.storage
8+
options:
9+
show_root_heading: true
10+
show_source: false
11+
members: true
12+
13+
## Unified Storage
14+
15+
::: audiomancer.storage.unified
16+
options:
17+
show_root_heading: true
18+
show_source: true

‎docs/api/templates.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Templates API Reference
2+
3+
The `audiomancer.templates` module provides project template functionality.
4+
5+
## Overview
6+
7+
::: audiomancer.templates
8+
options:
9+
show_root_heading: true
10+
show_source: false
11+
members: true

‎docs/configuration/examples.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Configuration Examples
2+
3+
## Minimal Global Config
4+
5+
```yaml
6+
# ~/.config/audiomancer/config.yaml
7+
library:
8+
source_dir: ~/Samples
9+
```
10+
11+
This is the minimum needed to use audiomancer. All other settings use builtin defaults.
12+
13+
## High-Performance Analysis
14+
15+
```yaml
16+
# ~/.config/audiomancer/config.yaml
17+
library:
18+
copy_workers: 32 # More parallel workers
19+
max_file_size_mb: 50 # Larger files allowed
20+
21+
analysis:
22+
max_file_size_mb: 100 # Analyze larger files
23+
embedding_dim: 256 # Higher quality embeddings
24+
```
25+
26+
## Multiple Sample Sources
27+
28+
```yaml
29+
# ~/.config/audiomancer/config.yaml
30+
sources:
31+
samples:
32+
paths:
33+
- ~/Music/Samples
34+
- ~/Library/Audio/Sample Libraries
35+
- /Volumes/External/Samples
36+
synths:
37+
paths:
38+
- ~/synths
39+
- ~/Library/Application Support/SuperCollider/synthdefs
40+
```
41+
42+
## Project-Specific Override
43+
44+
```yaml
45+
# .audiomancer.yaml (in project directory)
46+
library:
47+
project_root: ~/Development/my-music
48+
source_dir: ~/Library/CloudStorage/GoogleDrive/My Music Samples
49+
max_file_size_mb: 5 # Smaller files for this project
50+
51+
analysis:
52+
max_file_size_mb: 20 # Override global setting
53+
```
54+
55+
## Custom Storage Locations
56+
57+
```yaml
58+
# ~/.config/audiomancer/config.yaml
59+
storage:
60+
db_path: ~/Music/audiomancer/database.db
61+
embeddings_path: ~/Music/audiomancer/embeddings
62+
models_path: ~/Music/audiomancer/models
63+
```
64+
65+
## Next Steps
66+
67+
- [Configuration System](system.md) - How configuration works
68+
- [API Reference](../api/index.md) - Python configuration API

‎docs/configuration/system.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Configuration System
2+
3+
Audiomancer uses a three-tier configuration system with inheritance:
4+
5+
```
6+
1. Builtin defaults (hardcoded in config.py)
7+
↓
8+
2. Global config (~/.config/audiomancer/config.yaml)
9+
↓ (overrides)
10+
3. Project config (.audiomancer.yaml in project directory)
11+
↓ (overrides)
12+
Final merged configuration
13+
```
14+
15+
## Configuration Files
16+
17+
### Global Config
18+
19+
**Location**: `~/.config/audiomancer/config.yaml`
20+
21+
- Shared settings across all projects
22+
- Personal defaults (sample sources, analysis settings)
23+
- Optional - if missing, uses builtin defaults
24+
25+
### Project Config
26+
27+
**Location**: `.audiomancer.yaml` in project root
28+
29+
- Project-specific overrides
30+
- Auto-generated by `audiomancer init`
31+
- Auto-detected when starting MCP server in a project directory
32+
- Optional - if missing, uses global config or builtin defaults
33+
34+
## Example Global Config
35+
36+
`~/.config/audiomancer/config.yaml`:
37+
38+
```yaml
39+
# Sample library paths
40+
library:
41+
source_dir: ~/Library/CloudStorage/GoogleDrive/Samples # Where packs live
42+
auto_analyze: true
43+
max_file_size_mb: 10
44+
copy_workers: 16
45+
46+
# Analysis settings
47+
analysis:
48+
max_file_size_mb: 50
49+
embedding_dim: 128
50+
51+
# Sample sources (for scanning)
52+
sources:
53+
samples:
54+
paths:
55+
- ~/Music/Samples
56+
synths:
57+
paths:
58+
- ~/synths
59+
60+
# Storage paths
61+
storage:
62+
db_path: ~/.local/share/audiomancer/audiomancer.db
63+
embeddings_path: ~/.local/share/audiomancer/embeddings
64+
models_path: ~/.local/share/audiomancer/models
65+
```
66+
67+
## Example Project Config
68+
69+
`.audiomancer.yaml` (auto-generated by `audiomancer init`):
70+
71+
```yaml
72+
# Project-specific settings
73+
library:
74+
project_root: ~/Development/my-music # This project's root
75+
source_dir: ~/path/to/samples # Override global sample source
76+
77+
# Project can override any global setting
78+
analysis:
79+
max_file_size_mb: 20 # Different limit for this project
80+
```
81+
82+
## Config Auto-Detection
83+
84+
When running `audiomancer serve` or using MCP tools, the server automatically:
85+
86+
1. Searches upward from current directory for `.audiomancer.yaml`
87+
2. If found, uses that project as the context
88+
3. Merges project config with global config and builtin defaults
89+
4. All file paths in tools are relative to detected project root
90+
91+
This means Claude Code can automatically detect which project you're working in when you start the MCP server.
92+
93+
## Project Structure
94+
95+
```
96+
{project_root}/
97+
├── .audiomancer.yaml # Project-specific config
98+
├── .mcp.json # MCP server detection
99+
├── samples/ # Local cache (copied from source)
100+
├── library/ # Active samples (symlinks to samples/)
101+
├── session.tidal # TidalCycles session
102+
├── start_superdirt.scd # SuperDirt startup
103+
└── CLAUDE.md # Claude Code project instructions
104+
```
105+
106+
## Next Steps
107+
108+
- [Configuration Examples](examples.md) - More examples
109+
- [API Reference](../api/index.md) - Python configuration API

0 commit comments

Comments
 (0)