Skip to content

Commit 2b75261

Browse files
Lumi-nodeclaude
Lumi-node
and
claude
committed
feat: Add MkDocs Material documentation site with auto-deploy
- Landing page with feature cards and example output - Getting started: installation, MCP setup, CLI usage, concepts - Individual tool pages (9 tools) with usage, examples, and options - API reference pages using mkdocstrings (auto-generated from docstrings) - GitHub Actions workflow for auto-deploy to GitHub Pages on push Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent acfa90c commit 2b75261

21 files changed

Lines changed: 2013 additions & 0 deletions

‎.github/workflows/docs.yml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
name: Deploy Docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: "pages"
15+
cancel-in-progress: false
16+
17+
jobs:
18+
deploy:
19+
environment:
20+
name: github-pages
21+
url: ${{ steps.deployment.outputs.page_url }}
22+
runs-on: ubuntu-latest
23+
steps:
24+
- uses: actions/checkout@v4
25+
26+
- uses: actions/setup-python@v5
27+
with:
28+
python-version: '3.12'
29+
30+
- name: Install dependencies
31+
run: pip install mkdocs-material mkdocstrings[python]
32+
33+
- name: Build docs
34+
run: mkdocs build
35+
36+
- name: Upload artifact
37+
uses: actions/upload-pages-artifact@v3
38+
with:
39+
path: site/
40+
41+
- name: Deploy to GitHub Pages
42+
id: deployment
43+
uses: actions/deploy-pages@v4

‎docs/assets/Drydock.jpg‎

701 KB
Loading

‎docs/getting-started/cli-usage.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# CLI Quick Start
2+
3+
All Drydock tools work directly from the command line. No setup beyond cloning the repo.
4+
5+
## The One-Shot Command
6+
7+
```bash
8+
# Compile full project context (runs ALL analyzers)
9+
python Tools/analyzers/context_compiler.py /path/to/project -o context.json
10+
11+
# Human-readable version
12+
python Tools/analyzers/context_compiler.py /path/to/project --markdown -o context.md
13+
```
14+
15+
## Individual Tools
16+
17+
### Boundary Detector (the killer feature)
18+
19+
```bash
20+
python Tools/analyzers/boundary_detector.py /path/to/project -o boundaries.json
21+
```
22+
23+
Tells you exactly which clusters of files can be safely extracted, which files are bridges between components, and rates extraction risk.
24+
25+
### Code Map
26+
27+
```bash
28+
python Tools/analyzers/codemap.py /path/to/project -o codemap.json
29+
30+
# Markdown for humans
31+
python Tools/analyzers/codemap.py /path/to/project --markdown
32+
```
33+
34+
### Interface Extractor
35+
36+
```bash
37+
python Tools/analyzers/interface_extractor.py /path/to/project -o interfaces.json
38+
```
39+
40+
### Dependency Analyzer
41+
42+
```bash
43+
python Tools/analyzers/dependency_analyzer.py /path/to/project --json -o deps.json
44+
```
45+
46+
### Structure Analyzer
47+
48+
```bash
49+
python Tools/analyzers/structure_analyzer.py /path/to/project -o structure.md
50+
```
51+
52+
### Platform Detector
53+
54+
```bash
55+
python Tools/analyzers/platform_detector.py /path/to/project --json -o platforms.json
56+
```
57+
58+
### Git Analyzer
59+
60+
```bash
61+
# Requires a full clone (not --depth 1)
62+
python Tools/analyzers/git_analyzer.py /path/to/project --days 180 -o git.md
63+
```
64+
65+
## Full Workflow
66+
67+
```bash
68+
# 1. Bring a project in
69+
python Tools/intake/git_intake.py https://github.com/org/repo --shallow --analyze
70+
71+
# 2. Analyze it
72+
python Tools/analyzers/context_compiler.py Ship_Yard/_intake/repo -o context.json
73+
74+
# 3. Find extraction points
75+
python Tools/analyzers/boundary_detector.py Ship_Yard/_intake/repo -o boundaries.json
76+
77+
# 4. Scaffold a new project
78+
python Tools/scaffolders/project_scaffolder.py --name my-new-project
79+
80+
# 5. Build and ship
81+
python Tools/builders/oryx_builder.py release Projects/my-new-project --version v1.0.0
82+
```
83+
84+
## Output Formats
85+
86+
All analyzers support two output modes:
87+
88+
| Flag | Format | Best for |
89+
|------|--------|----------|
90+
| *(default)* | JSON | AI agents, programmatic consumption |
91+
| `--markdown` | Markdown | Human review, documentation |
92+
93+
Use `-o filename` to write to a file, or omit to print to stdout.

‎docs/getting-started/concepts.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Concepts
2+
3+
## The Drydock Metaphor
4+
5+
Like a naval drydock where ships are brought in for major overhauls, Drydock is a workspace for software architecture work:
6+
7+
- **Ships** = Software projects
8+
- **Ocean** = Production / upstream repos
9+
- **Ship Yard** = Where projects are analyzed and decomposed
10+
- **Drydock** = Your workspace where the real work happens
11+
12+
## The Lifecycle
13+
14+
```
15+
┌─────────────────────────────────────────────────────────────────────────────┐
16+
│ │
17+
│ OCEAN DRYDOCK OCEAN │
18+
│ (upstream) (your yard) (downstream) │
19+
│ │
20+
│ ┌─────────┐ ┌───────────────────────────────────┐ ┌─────────┐ │
21+
│ │ GitHub │ │ │ │ Your │ │
22+
│ │ GitLab │ ──▶ │ INTAKE → WORK → RELEASE → SHIP │ ──▶ │ Prod │ │
23+
│ │ etc. │ │ │ │ Deploy │ │
24+
│ └─────────┘ └───────────────────────────────────┘ └─────────┘ │
25+
│ │
26+
│ Ships arrive Ships get rebuilt with new parts Ships return to sea │
27+
│ for overhaul as new vessels │
28+
│ │
29+
└─────────────────────────────────────────────────────────────────────────────┘
30+
```
31+
32+
### Phases
33+
34+
1. **Intake** — Clone/link upstream projects into `Ship_Yard/_intake/` (read-only)
35+
2. **Analysis** — Run analyzers, document architecture in `Ship_Yard/_analysis/`
36+
3. **Extraction** — Pull out reusable components into `Ship_Yard/_extraction/`
37+
4. **Assembly** — Combine extracted parts into new projects in `Projects/`
38+
5. **Release** — Stage for deployment in `Release/`
39+
6. **Ship** — Deploy to production, track in `Ocean/`
40+
41+
## Directory Structure
42+
43+
```
44+
Drydock/
45+
├── StartHere/ # Documentation, guides, templates
46+
├── Ship_Yard/ # Incoming projects for decomposition
47+
│ ├── _intake/ # Raw project clones (READ-ONLY)
48+
│ ├── _analysis/ # Analysis documents
49+
│ └── _extraction/ # Extracted components
50+
├── Tools/ # Utilities for drydock operations
51+
│ ├── mcp_server.py # MCP server for AI assistants
52+
│ ├── intake/ # Project intake tools
53+
│ ├── analyzers/ # Code analysis tools
54+
│ ├── scaffolders/ # Project scaffolding tools
55+
│ └── builders/ # Build and ship tools
56+
├── Projects/ # New projects being assembled
57+
├── Workbench/ # Experiments and prototypes
58+
├── Release/ # Launch preparation
59+
└── Ocean/ # Deployed fleet registry
60+
```
61+
62+
## Design Principles
63+
64+
- **JSON-first** — All tools default to JSON for AI consumption, `--markdown` for humans
65+
- **Pure stdlib** — Zero external dependencies (except `mcp` for the MCP server)
66+
- **Non-destructive** — Analyzers never modify source projects
67+
- **Composable** — Each tool does one thing; `context_compiler` orchestrates all
68+
- **No fat files** — Keep files under 300 lines where possible
69+
70+
## Key Analyzer Concepts
71+
72+
### Clusters
73+
Groups of files that import each other heavily. High internal connectivity = cohesive component.
74+
75+
### Bridge Files
76+
Files that connect multiple clusters. Extract these carefully — they're the glue between components.
77+
78+
### Orphans
79+
Files with no import relationships. Easy to extract or remove without breaking anything.
80+
81+
### Extraction Risk
82+
- **Low** — Zero external dependencies. Can be extracted cleanly.
83+
- **Medium** — A few external deps. Extractable with some interface work.
84+
- **High** — Many external deps. Extraction requires significant refactoring.

‎docs/getting-started/installation.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Installation
2+
3+
Drydock is pure Python (stdlib only). No package manager needed for the core tools.
4+
5+
## Clone the Repo
6+
7+
```bash
8+
git clone https://github.com/lumi-node/Drydock.git
9+
cd Drydock
10+
```
11+
12+
That's it. All analyzers work immediately:
13+
14+
```bash
15+
python Tools/analyzers/codemap.py --help
16+
```
17+
18+
## For MCP Server (optional)
19+
20+
If you want to use Drydock from an AI assistant (Claude Code, Cursor, VS Code):
21+
22+
```bash
23+
pip install mcp
24+
```
25+
26+
Then see [MCP Setup](mcp-setup.md).
27+
28+
## Requirements
29+
30+
- **Python 3.10+**
31+
- **git** (for `git_intake.py` and `git_analyzer.py`)
32+
- **Docker** (only for `oryx_builder.py`, optional)
33+
34+
## Verify Installation
35+
36+
```bash
37+
# Run the code map against Drydock itself
38+
python Tools/analyzers/codemap.py . --markdown
39+
40+
# Should output a complete map of the Drydock codebase
41+
```

‎docs/getting-started/mcp-setup.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# MCP Server Setup
2+
3+
Drydock ships as an MCP (Model Context Protocol) server. This lets AI coding assistants call the analyzers directly as tool calls.
4+
5+
## Install
6+
7+
```bash
8+
pip install mcp
9+
```
10+
11+
## Configure Your Assistant
12+
13+
=== "Claude Code"
14+
15+
Add to `~/.claude/settings.json`:
16+
17+
```json
18+
{
19+
"mcpServers": {
20+
"drydock": {
21+
"command": "python",
22+
"args": ["/path/to/Drydock/Tools/mcp_server.py"]
23+
}
24+
}
25+
}
26+
```
27+
28+
=== "VS Code"
29+
30+
Add to `.vscode/mcp.json` in your workspace:
31+
32+
```json
33+
{
34+
"servers": {
35+
"drydock": {
36+
"command": "python",
37+
"args": ["/path/to/Drydock/Tools/mcp_server.py"]
38+
}
39+
}
40+
}
41+
```
42+
43+
=== "Cursor"
44+
45+
Add to your MCP settings:
46+
47+
```json
48+
{
49+
"mcpServers": {
50+
"drydock": {
51+
"command": "python",
52+
"args": ["/path/to/Drydock/Tools/mcp_server.py"]
53+
}
54+
}
55+
}
56+
```
57+
58+
!!! tip
59+
Replace `/path/to/Drydock` with the actual path where you cloned the repo.
60+
61+
## Available Tools
62+
63+
Once configured, your AI assistant can call these tools:
64+
65+
| Tool | Ask your assistant... |
66+
|------|----------------------|
67+
| `drydock_context` | "Give me a full analysis of this project" |
68+
| `drydock_codemap` | "Map the files and functions in this codebase" |
69+
| `drydock_boundaries` | "Can I safely extract this component?" |
70+
| `drydock_dependencies` | "What does this project depend on?" |
71+
| `drydock_interfaces` | "What does each module expose publicly?" |
72+
| `drydock_structure` | "How big is this codebase?" |
73+
| `drydock_platforms` | "What tech stack is this project using?" |
74+
75+
## Example
76+
77+
After setup, just ask naturally:
78+
79+
> "Analyze the boundaries of the project at /home/me/my-app"
80+
81+
Your assistant calls `drydock_boundaries` and gets back:
82+
83+
```json
84+
{
85+
"summary": {
86+
"total_source_files": 42,
87+
"clusters_found": 3,
88+
"bridge_files": 2,
89+
"orphan_files": 5
90+
},
91+
"extraction_suggestions": [
92+
{
93+
"name": "auth",
94+
"files": 8,
95+
"extraction_risk": "low",
96+
"reason": "No external dependencies - clean extraction"
97+
},
98+
{
99+
"name": "api",
100+
"files": 15,
101+
"extraction_risk": "medium",
102+
"reason": "3 external deps, 2 external dependents"
103+
}
104+
]
105+
}
106+
```
107+
108+
The assistant can then reason about extraction decisions using real data.

0 commit comments

Comments
 (0)