Skip to content

Commit 16b510f

Browse files
crimson-knightcrimson-knight
committed
feat: implement comprehensive documentation system
- Add comprehensive documentation module with 11 detailed guides - Create automated GitHub Pages deployment via GitHub Actions - Implement local documentation generation script - Update README with professional layout and documentation links - Remove legacy CLI framework dependencies - Add complete command reference and troubleshooting guides - Configure SEO optimization with sitemaps and canonical URLs - Zero external dependencies - uses Crystal's native docs system Documentation will be available at: https://amberframework.github.io/amber_cli/
1 parent 0b40840 commit 16b510f

File tree

12 files changed

+618
-168
lines changed

12 files changed

+618
-168
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
name: Generate and Deploy Documentation
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
branches: [ main ]
8+
# Allow manual trigger
9+
workflow_dispatch:
10+
11+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
18+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
19+
concurrency:
20+
group: "pages"
21+
cancel-in-progress: false
22+
23+
jobs:
24+
# Generate documentation
25+
generate-docs:
26+
runs-on: ubuntu-latest
27+
steps:
28+
- name: Checkout
29+
uses: actions/checkout@v4
30+
31+
- name: Install Crystal
32+
uses: crystal-lang/install-crystal@v1
33+
with:
34+
crystal: latest
35+
36+
- name: Install dependencies
37+
run: shards install
38+
39+
- name: Generate documentation
40+
run: |
41+
crystal docs \
42+
--project-name="Amber CLI" \
43+
--project-version="${GITHUB_REF_NAME:-main}" \
44+
--source-url-pattern="https://github.com/amberframework/amber_cli/blob/%{refname}/%{path}#L%{line}" \
45+
--output=docs \
46+
--format=html \
47+
--sitemap-base-url="https://amberframework.github.io/amber_cli/" \
48+
--canonical-base-url="https://amberframework.github.io/amber_cli/"
49+
50+
- name: Setup Pages
51+
if: github.ref == 'refs/heads/main'
52+
uses: actions/configure-pages@v4
53+
54+
- name: Upload artifact
55+
if: github.ref == 'refs/heads/main'
56+
uses: actions/upload-pages-artifact@v3
57+
with:
58+
path: ./docs
59+
60+
# Deploy to GitHub Pages (only on main branch)
61+
deploy-docs:
62+
if: github.ref == 'refs/heads/main'
63+
environment:
64+
name: github-pages
65+
url: ${{ steps.deployment.outputs.page_url }}
66+
runs-on: ubuntu-latest
67+
needs: generate-docs
68+
steps:
69+
- name: Deploy to GitHub Pages
70+
id: deployment
71+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,33 @@
1-
/docs/
1+
# Dependencies
22
/lib/
33
/bin/
4-
/.shards/
4+
5+
# Generated files
56
*.dwarf
67

8+
# Editor files
9+
.vscode/
10+
*.swp
11+
*.swo
12+
*~
13+
14+
# OS files
15+
.DS_Store
16+
Thumbs.db
17+
18+
# Test files
19+
/tmp/
20+
21+
# Generated documentation (keep structure, ignore generated content)
22+
/docs/**
23+
!/docs/README.md
24+
!/docs/.gitkeep
25+
26+
# Build artifacts
27+
amber
28+
amber_cli
29+
/target/
30+
731
# Libraries don't need dependency lock
832
# Dependencies will be locked in applications that use them
933
/shard.lock
10-
/amber_cli

‎DOCUMENTATION_SETUP.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# Amber CLI Documentation System
2+
3+
## Overview
4+
5+
We have successfully implemented a comprehensive, automated documentation system for the Amber CLI that leverages Crystal's built-in `crystal docs` command and GitHub Pages for hosting.
6+
7+
## 🎯 Key Features
8+
9+
### **Automated Documentation Generation**
10+
- Uses Crystal's native `crystal docs` command
11+
- Zero external dependencies for documentation
12+
- Automatically extracts API documentation from code comments
13+
- Generates beautiful, searchable HTML documentation
14+
15+
### **Comprehensive Content**
16+
- **API Reference** - Automatically generated from code
17+
- **User Guides** - Comprehensive guides in `src/amber_cli/documentation.cr`
18+
- **Command Reference** - Detailed command usage and examples
19+
- **Configuration Reference** - All configuration options
20+
- **Troubleshooting** - Common issues and solutions
21+
22+
### **GitHub Pages Integration**
23+
- Automatic deployment via GitHub Actions
24+
- Documentation updates on every push to main
25+
- Hosted at: https://amberframework.github.io/amber_cli/
26+
- SEO-optimized with sitemaps and canonical URLs
27+
28+
## 📁 Structure
29+
30+
```
31+
amber_cli/
32+
├── src/amber_cli/documentation.cr # Comprehensive documentation module
33+
├── docs/ # Generated documentation (ignored in git)
34+
│ ├── README.md # Documentation guide
35+
│ └── .gitkeep # Ensures directory exists
36+
├── scripts/generate_docs.sh # Local documentation generation
37+
├── .github/workflows/docs.yml # GitHub Actions workflow
38+
└── README.md # Updated with links to docs
39+
```
40+
41+
## 🚀 How It Works
42+
43+
### **Local Development**
44+
```bash
45+
# Generate documentation locally
46+
./scripts/generate_docs.sh
47+
48+
# Manual generation
49+
crystal docs --project-name="Amber CLI" --output=docs
50+
51+
# Serve locally
52+
cd docs && python -m http.server 8000
53+
```
54+
55+
### **Automatic Deployment**
56+
1. **Trigger**: Push to `main` branch
57+
2. **Generate**: Crystal docs with full configuration
58+
3. **Deploy**: Upload to GitHub Pages
59+
4. **Live**: Available within minutes
60+
61+
### **Documentation Sources**
62+
1. **Code Comments** - Crystal docstrings throughout codebase
63+
2. **Documentation Module** - Comprehensive guides and examples
64+
3. **README** - Quick start and overview
65+
4. **Command Help** - Integrated help system
66+
67+
## 📝 Content Organization
68+
69+
### **Main Documentation Classes**
70+
- `Overview` - Introduction and quick start
71+
- `NewCommand` - Creating new applications
72+
- `DatabaseCommand` - Database management
73+
- `GenerationSystem` - Code generation
74+
- `DevelopmentTools` - Watch mode and exec
75+
- `ApplicationAnalysis` - Routes and pipelines
76+
- `SecurityAndConfiguration` - Encryption and config
77+
- `PluginSystem` - Plugin management
78+
- `CommandReference` - Complete command reference
79+
- `ConfigurationReference` - All configuration options
80+
- `Troubleshooting` - Common issues and solutions
81+
82+
### **Crystal Documentation Features Used**
83+
- **Markdown Support** - Rich formatting in docstrings
84+
- **Code Examples** - Syntax-highlighted code blocks
85+
- **Cross-references** - Automatic linking between classes/methods
86+
- **Admonitions** - NOTE, WARNING, TODO, etc.
87+
- **Parameter Documentation** - Italicized parameter names
88+
- **Inheritance** - Automatic documentation inheritance
89+
90+
## 🔧 Configuration
91+
92+
### **GitHub Actions Workflow**
93+
```yaml
94+
# .github/workflows/docs.yml
95+
- Installs Crystal
96+
- Generates documentation with full options
97+
- Configures GitHub Pages
98+
- Deploys automatically
99+
```
100+
101+
### **Documentation Generation Options**
102+
```bash
103+
crystal docs \
104+
--project-name="Amber CLI" \
105+
--project-version="${VERSION}" \
106+
--source-url-pattern="github_pattern" \
107+
--output=docs \
108+
--format=html \
109+
--sitemap-base-url="base_url" \
110+
--canonical-base-url="canonical_url"
111+
```
112+
113+
## 🎨 Benefits Achieved
114+
115+
### **For Users**
116+
- **Easy Discovery** - Links in README to comprehensive docs
117+
- **Quick Start** - Clear examples and getting started guide
118+
- **Complete Reference** - Every command and option documented
119+
- **Searchable** - Full-text search in documentation
120+
- **Always Current** - Automatically updated with code changes
121+
122+
### **For Developers**
123+
- **Low Maintenance** - Documentation in code comments
124+
- **Automatic Updates** - No manual deployment needed
125+
- **Crystal Native** - Uses Crystal's built-in documentation system
126+
- **Version Tracking** - Documentation versioned with code
127+
- **Easy Contributing** - Clear documentation standards
128+
129+
### **For the Project**
130+
- **Professional Appearance** - Beautiful, searchable docs
131+
- **SEO Benefits** - Proper meta tags and sitemaps
132+
- **Accessibility** - Crystal docs generate accessible HTML
133+
- **Mobile Friendly** - Responsive documentation layout
134+
- **Fast Loading** - Static site generation
135+
136+
## 📋 Maintenance
137+
138+
### **Adding Documentation**
139+
1. **Code Comments** - Add Crystal docstrings to classes/methods
140+
2. **Documentation Module** - Update `src/amber_cli/documentation.cr`
141+
3. **Examples** - Include usage examples in comments
142+
4. **Test Locally** - Run `./scripts/generate_docs.sh`
143+
144+
### **Documentation Standards**
145+
- Use Crystal's documentation format
146+
- Include examples for complex features
147+
- Link to related functionality
148+
- Keep language clear and concise
149+
- Test documentation generation before PR
150+
151+
### **Automatic Updates**
152+
- Documentation rebuilds on every push to main
153+
- Links to source code automatically updated
154+
- Version information tracked from git
155+
- Search index automatically regenerated
156+
157+
## 🔗 Links
158+
159+
- **Live Documentation**: https://amberframework.github.io/amber_cli/
160+
- **Crystal Docs Reference**: https://crystal-lang.org/reference/1.16/syntax_and_semantics/documenting_code.html
161+
- **GitHub Repository**: https://github.com/amberframework/amber_cli
162+
- **Local Generation Script**: `./scripts/generate_docs.sh`
163+
164+
## ✅ Success Metrics
165+
166+
- ✅ **Zero External Dependencies** - Uses only Crystal stdlib
167+
- ✅ **Automatic Generation** - No manual intervention needed
168+
- ✅ **Comprehensive Coverage** - All features documented
169+
- ✅ **GitHub Pages Integration** - Seamless hosting
170+
- ✅ **Local Development** - Easy local generation
171+
- ✅ **Search Functionality** - Full-text search available
172+
- ✅ **Mobile Responsive** - Works on all devices
173+
- ✅ **SEO Optimized** - Proper meta tags and structure
174+
- ✅ **Version Tracking** - Documentation follows code versions
175+
- ✅ **Professional Quality** - Production-ready documentation
176+
177+
This documentation system provides a solid foundation for maintaining comprehensive, up-to-date documentation for the Amber CLI project while minimizing maintenance overhead and maximizing discoverability.

0 commit comments

Comments
 (0)