Skip to content

Commit b4977a7

Browse files
committed
fix: wip
1 parent 44841ca commit b4977a7

4 files changed

Lines changed: 99 additions & 27 deletions

File tree

‎.claude/settings.local.json‎

Lines changed: 0 additions & 25 deletions
This file was deleted.

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,3 +49,4 @@ pip-delete-this-directory.txt
4949
# OS
5050
.DS_Store
5151
Thumbs.db
52+
.claude/settings.local.json

‎CLAUDE.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
aidocs is a Python CLI tool that generates AI-powered documentation for web applications. It installs slash commands into Claude Code projects (e.g., `/docs:generate`, `/docs:flow`) that combine vision analysis, codebase analysis, and interactive UI exploration to produce comprehensive documentation.
8+
9+
## Development Commands
10+
11+
```bash
12+
# Setup development environment
13+
uv venv && uv pip install -e .
14+
15+
# Run CLI
16+
aidocs check # Check environment/dependencies
17+
aidocs init . # Install docs module in current project
18+
aidocs version # Show version
19+
20+
# RAG/Embeddings workflow
21+
aidocs rag-chunks docs/ # Chunk markdown files for vector DB
22+
aidocs rag-vectors # Generate embeddings (requires OPENAI_API_KEY)
23+
24+
# Documentation server
25+
aidocs serve # Serve docs with MkDocs Material
26+
aidocs serve --build # Build static site
27+
28+
# PDF export
29+
aidocs export-pdf docs/page.md
30+
```
31+
32+
## Architecture
33+
34+
```
35+
src/aidocs_cli/
36+
├── __init__.py # Version and entry point
37+
├── cli.py # Typer CLI commands (init, check, serve, rag-*, export-pdf)
38+
├── installer.py # Copies templates to target project (.claude/commands/, .claude/workflows/)
39+
├── chunker.py # Splits markdown at ## headings for RAG
40+
├── embeddings.py # OpenAI embeddings + SQL generation for pgvector
41+
├── server.py # MkDocs config generation and nav discovery
42+
├── pdf_exporter.py # Markdown→HTML→PDF with Chrome/Playwright
43+
└── templates/
44+
├── commands/docs/ # Slash command definitions (*.md)
45+
└── workflows/ # Workflow implementations per command
46+
```
47+
48+
### Key Components
49+
50+
- **CLI (cli.py)**: Uses Typer with Rich for terminal UI. Entry point is `app()`.
51+
- **Installer**: Copies command/workflow templates to target project's `.claude/` directory (or `.cursor/` for Cursor).
52+
- **Chunker**: Creates `.chunks.json` files alongside markdown, tracks changes via `docs/.chunks/manifest.json`.
53+
- **Embeddings**: Calls OpenAI API (text-embedding-3-small, 1536 dimensions), outputs `docs/.chunks/sync.sql` for pgvector import.
54+
- **Server**: Auto-discovers nav structure from folder hierarchy, generates ephemeral `mkdocs.yml`.
55+
56+
### Slash Commands Flow
57+
58+
When `aidocs init` runs:
59+
1. Templates from `src/aidocs_cli/templates/` are copied to project's `.claude/commands/docs/` and `.claude/workflows/docs/`
60+
2. Each command (e.g., `generate.md`) references a workflow that defines the multi-step process
61+
3. Workflows use Playwright MCP for browser automation when needed
62+
63+
## Version Management
64+
65+
Version is defined in two places (keep in sync):
66+
- `pyproject.toml` → `version = "X.Y.Z"`
67+
- `src/aidocs_cli/__init__.py` → `__version__ = "X.Y.Z"`
68+
69+
## Release Process
70+
71+
1. Update version in both files
72+
2. Commit and push to main
73+
3. Create GitHub release → triggers `.github/workflows/publish.yml` (PyPI) and `.github/workflows/update-homebrew.yml`
74+
75+
## Dependencies
76+
77+
Core: typer, rich, httpx, mkdocs, mkdocs-material, pyyaml
78+
79+
Python 3.11+ required. Build system uses hatchling.
80+
81+
## Environment Variables
82+
83+
- `OPENAI_API_KEY`: Required for `rag-vectors` command (embedding generation)

‎src/aidocs_cli/server.py‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -129,8 +129,18 @@ def generate_mkdocs_config(
129129
},
130130
"markdown_extensions": [
131131
"pymdownx.highlight",
132-
"pymdownx.superfences",
133-
"pymdownx.tabbed",
132+
{
133+
"pymdownx.superfences": {
134+
"custom_fences": [
135+
{
136+
"name": "mermaid",
137+
"class": "mermaid",
138+
"format": "!!python/name:pymdownx.superfences.fence_code_format",
139+
}
140+
]
141+
}
142+
},
143+
{"pymdownx.tabbed": {"alternate_style": True}},
134144
"pymdownx.details",
135145
"admonition",
136146
"tables",
@@ -143,6 +153,9 @@ def generate_mkdocs_config(
143153
"extra": {
144154
"generator": False,
145155
},
156+
"extra_javascript": [
157+
"https://unpkg.com/mermaid@10/dist/mermaid.min.js",
158+
],
146159
}
147160

148161
if nav:

0 commit comments

Comments
 (0)