aesthetic.computer
Monorepo for Aesthetic.Computer
aesthetic.computer
1# CLI Documentation Explorer for Aesthetic Computer
2
3*Specification for command-line documentation browsing and Emacs integration*
4
5## Overview
6
7A command-line documentation explorer that provides fast access to Aesthetic Computer documentation, similar to the existing `kidlisp-tools` CLI interface. This tool will integrate with Emacs to provide a 'docs' tab alongside or replacing the current 'code' tab.
8
9## CLI Tool Specification
10
11### Command Structure
12```bash
13ac-docs [command] [options]
14```
15
16### Core Commands
17
18#### `ac-docs search <query>`
19Search across all documentation:
20```bash
21ac-docs search "wipe" # Find all references to wipe function
22ac-docs search "pointer" # Find pointer/input documentation
23ac-docs search "kidlisp circle" # Find KidLisp circle function
24```
25
26#### `ac-docs api [function]`
27Browse JavaScript API documentation:
28```bash
29ac-docs api # List all API categories
30ac-docs api graphics # Show graphics functions
31ac-docs api wipe # Show detailed wipe function info
32ac-docs api --examples box # Show box function with examples
33```
34
35#### `ac-docs kidlisp [topic]`
36Browse KidLisp language documentation:
37```bash
38ac-docs kidlisp # Show language overview
39ac-docs kidlisp syntax # Basic syntax guide
40ac-docs kidlisp functions # List all functions
41ac-docs kidlisp circle # Show circle function details
42ac-docs kidlisp --examples # Show example programs
43```
44
45#### `ac-docs pieces [name]`
46Browse piece documentation:
47```bash
48ac-docs pieces # List documented pieces
49ac-docs pieces structure # Show piece lifecycle info
50ac-docs pieces template # Show piece templates
51ac-docs pieces paint-canvas # Show specific piece docs
52```
53
54#### `ac-docs coverage`
55Show documentation coverage reports:
56```bash
57ac-docs coverage # Overall coverage summary
58ac-docs coverage api # API documentation coverage
59ac-docs coverage pieces # Piece documentation coverage
60ac-docs coverage --missing # Show undocumented functions
61```
62
63#### `ac-docs update`
64Update documentation cache and analysis:
65```bash
66ac-docs update # Refresh all documentation
67ac-docs update api # Re-analyze API only
68ac-docs update --force # Force full rebuild
69```
70
71### Interactive Mode
72
73#### `ac-docs interactive` or `ac-docs`
74Launch interactive browser:
75```
76📚 Aesthetic Computer Documentation Explorer
77
78Categories:
79 1. JavaScript API Reference
80 2. KidLisp Language Guide
81 3. Piece Documentation
82 4. System Architecture
83 5. Development Tools
84
85Search: [_________________]
86
87>
88```
89
90Navigation commands:
91- `1-5` - Select category
92- `/query` - Search
93- `help` - Show help
94- `back` - Go back
95- `quit` - Exit
96
97### Output Formatting
98
99#### Terminal Output
100- **Syntax highlighting** for code examples
101- **Colored headers** and sections
102- **Tables** for function parameters
103- **Breadcrumb navigation** showing current location
104- **Paging** for long content
105
106#### Example Output
107```bash
108$ ac-docs api wipe
109
110📚 JavaScript API > Graphics > wipe
111
112wipe(color) → void
113Clear the entire screen with the specified color.
114
115Parameters:
116 color string|number|array Color value (name, RGB, etc.)
117
118Examples:
119 wipe("black") // Clear with black
120 wipe(255, 0, 0) // Clear with red RGB
121 wipe([100, 200, 255]) // Clear with RGB array
122
123Related:
124 → ink() Set drawing color
125 → box() Draw filled rectangle
126 → screen Get screen dimensions
127
128Used in pieces: paint-canvas, drawing-app, generative-art (+15 more)
129
130📖 Full documentation: /reference/api/javascript-api.md#wipe
131```
132
133## Emacs Integration
134
135### Configuration Addition
136Add to Emacs config to replace or supplement the 'code' tab:
137
138```elisp
139;; Aesthetic Computer Documentation Tab
140(defun ac-docs-tab ()
141 "Open Aesthetic Computer documentation explorer"
142 (interactive)
143 (split-window-right)
144 (other-window 1)
145 (ansi-term "ac-docs interactive" "ac-docs"))
146
147;; Key bindings
148(global-set-key (kbd "C-c d") 'ac-docs-tab)
149(global-set-key (kbd "C-c C-d") 'ac-docs-search)
150
151;; Function to search docs from current word
152(defun ac-docs-search ()
153 "Search AC docs for word at point"
154 (interactive)
155 (let ((word (thing-at-point 'word)))
156 (if word
157 (shell-command (format "ac-docs search '%s'" word))
158 (call-interactively 'ac-docs-search-prompt))))
159
160(defun ac-docs-search-prompt ()
161 "Prompt for search term and search AC docs"
162 (interactive)
163 (let ((query (read-string "Search AC docs: ")))
164 (shell-command (format "ac-docs search '%s'" query))))
165```
166
167### Workflow Integration
168
169#### Development Workflow
1701. **Coding**: Write AC piece in main Emacs buffer
1712. **Reference**: `C-c d` to open docs tab
1723. **Search**: Cursor on function name, `C-c C-d` to search
1734. **Browse**: Navigate documentation in side panel
1745. **Copy**: Copy examples or syntax back to code
175
176#### Tab Configuration Options
177```elisp
178;; Option 1: Replace 'code' tab with 'docs' tab
179(setq ac-default-tab 'docs)
180
181;; Option 2: Add 'docs' tab alongside 'code' tab
182(setq ac-tabs '(code docs kidlisp))
183
184;; Option 3: Context-sensitive tab switching
185(defun ac-smart-tab ()
186 "Show docs tab when editing AC pieces, code tab otherwise"
187 (if (ac-piece-file-p (buffer-file-name))
188 (ac-docs-tab)
189 (ac-code-tab)))
190```
191
192## Implementation Architecture
193
194### File Structure
195```
196tools/ac-docs/
197├── src/
198│ ├── cli.mjs # Main CLI interface
199│ ├── search.mjs # Search functionality
200│ ├── display.mjs # Terminal output formatting
201│ ├── cache.mjs # Documentation caching
202│ └── interactive.mjs # Interactive mode
203├── templates/ # Output templates
204├── cache/ # Cached documentation data
205└── package.json
206```
207
208### Data Sources
209- **API Reference**: Generated from `disk.mjs` analysis
210- **KidLisp Docs**: Extracted from `kidlisp.mjs`
211- **Piece Docs**: Scanned from `/reference/pieces/`
212- **Examples**: Collected from existing pieces
213- **Usage Data**: Cross-referenced from piece analysis
214
215### Caching Strategy
216- **Fast Startup**: Pre-generated documentation cache
217- **Auto-Update**: Detect changes in source files
218- **Incremental**: Update only changed sections
219- **Fallback**: Graceful degradation if cache is stale
220
221## Dependencies
222
223### Core Dependencies
224- **Commander.js**: CLI argument parsing
225- **Inquirer.js**: Interactive prompts and menus
226- **Chalk**: Terminal colors and formatting
227- **Marked**: Markdown parsing and rendering
228- **Fuse.js**: Fuzzy search across documentation
229
230### Optional Dependencies
231- **Blessed**: Enhanced terminal UI (for advanced interactive mode)
232- **Highlight.js**: Syntax highlighting for code examples
233- **Terminal-image**: Display images in terminal (for piece previews)
234
235## Development Phases
236
237### Phase 1: Basic CLI
238- [ ] Core command structure
239- [ ] Search functionality
240- [ ] API reference browsing
241- [ ] Simple output formatting
242
243### Phase 2: Interactive Mode
244- [ ] Menu-driven navigation
245- [ ] Enhanced search interface
246- [ ] Syntax highlighting
247- [ ] Paging and scrolling
248
249### Phase 3: Emacs Integration
250- [ ] Emacs Lisp functions
251- [ ] Key binding configuration
252- [ ] Tab integration
253- [ ] Context-sensitive help
254
255### Phase 4: Advanced Features
256- [ ] Visual piece previews
257- [ ] Usage analytics
258- [ ] Bookmark system
259- [ ] Documentation editing mode
260
261## Usage Examples
262
263### Developer Workflow Example
264```bash
265# Starting development
266$ cd aesthetic-computer/system/public/aesthetic.computer/disks/
267$ emacs my-piece.mjs
268
269# In Emacs: C-c d (open docs tab)
270# Terminal shows: ac-docs interactive
271
272# Quick API lookup
273$ ac-docs api circle
274# Shows circle function documentation
275
276# Search for pattern examples
277$ ac-docs search "animation loop"
278# Shows pieces and docs related to animation
279
280# Check what's undocumented
281$ ac-docs coverage --missing
282# Shows API functions needing documentation
283```
284
285### Integration with Existing Tools
286- **kidlisp-tools**: Share common CLI patterns and utilities
287- **VS Code extension**: Potentially share documentation data
288- **Web docs**: Export to same format as docs.js endpoint
289- **Development scripts**: Integration with build and test tools
290
291## Future Enhancements
292
293- **Live Documentation**: Real-time docs as you edit code
294- **AI Integration**: Natural language queries
295- **Visual Browser**: GUI version of the CLI tool
296- **Community Docs**: User-contributed documentation system
297- **Offline Mode**: Full functionality without network
298
299---
300
301*This specification provides the foundation for a comprehensive CLI documentation system that integrates seamlessly with existing AC development workflows.*