095fd89ff7
Some checks failed
CI/CD Pipeline / Test Suite (push) Has been cancelled
CI/CD Pipeline / Security Audit (push) Has been cancelled
CI/CD Pipeline / Build Docker Image (push) Has been cancelled
CI/CD Pipeline / Deploy to Staging (push) Has been cancelled
CI/CD Pipeline / Deploy to Production (push) Has been cancelled
CI/CD Pipeline / Performance Benchmarks (push) Has been cancelled
CI/CD Pipeline / Cleanup (push) Has been cancelled
233 lines
5.3 KiB
Markdown
233 lines
5.3 KiB
Markdown
# Documentation Scripts - Quick Reference
|
|
|
|
## 📁 Script Organization
|
|
|
|
All documentation-related scripts are now organized in `scripts/docs/`:
|
|
|
|
```
|
|
scripts/docs/
|
|
├── README.md # Comprehensive documentation
|
|
├── QUICK_REFERENCE.md # This file
|
|
├── build-docs.sh # Main build system
|
|
├── enhance-docs.sh # Cargo doc logo enhancement
|
|
├── docs-dev.sh # Development server
|
|
├── setup-docs.sh # Initial setup
|
|
├── deploy-docs.sh # Deployment automation
|
|
└── generate-content.sh # Content generation
|
|
```
|
|
|
|
## ⚡ Common Commands
|
|
|
|
### Quick Start
|
|
```bash
|
|
# Build all documentation with logos
|
|
./scripts/docs/build-docs.sh --all
|
|
|
|
# Start development server
|
|
./scripts/docs/docs-dev.sh
|
|
|
|
# Enhance cargo docs with logos
|
|
cargo doc --no-deps && ./scripts/docs/enhance-docs.sh
|
|
```
|
|
|
|
### Development Workflow
|
|
```bash
|
|
# 1. Setup (first time only)
|
|
./scripts/docs/setup-docs.sh --full
|
|
|
|
# 2. Start dev server with live reload
|
|
./scripts/docs/docs-dev.sh --open
|
|
|
|
# 3. Build and test
|
|
./scripts/docs/build-docs.sh --watch
|
|
```
|
|
|
|
### Production Deployment
|
|
```bash
|
|
# Build everything
|
|
./scripts/docs/build-docs.sh --all
|
|
|
|
# Deploy to GitHub Pages
|
|
./scripts/docs/deploy-docs.sh github-pages
|
|
|
|
# Deploy to Netlify
|
|
./scripts/docs/deploy-docs.sh netlify
|
|
```
|
|
|
|
## 🔧 Individual Scripts
|
|
|
|
### `build-docs.sh` - Main Build System
|
|
```bash
|
|
./scripts/docs/build-docs.sh [OPTIONS]
|
|
|
|
OPTIONS:
|
|
(none) Build mdBook only
|
|
--cargo Build cargo doc with logo enhancement
|
|
--all Build both mdBook and cargo doc
|
|
--serve Serve documentation locally
|
|
--watch Watch for changes and rebuild
|
|
--sync Sync existing docs into mdBook
|
|
```
|
|
|
|
### `enhance-docs.sh` - Logo Enhancement
|
|
```bash
|
|
./scripts/docs/enhance-docs.sh [OPTIONS]
|
|
|
|
OPTIONS:
|
|
(none) Enhance cargo doc with logos
|
|
--clean Remove backup files
|
|
--restore Restore original files
|
|
```
|
|
|
|
### `docs-dev.sh` - Development Server
|
|
```bash
|
|
./scripts/docs/docs-dev.sh [OPTIONS]
|
|
|
|
OPTIONS:
|
|
(none) Start on default port (3000)
|
|
--port N Use custom port
|
|
--open Auto-open browser
|
|
```
|
|
|
|
### `setup-docs.sh` - Initial Setup
|
|
```bash
|
|
./scripts/docs/setup-docs.sh [OPTIONS]
|
|
|
|
OPTIONS:
|
|
(none) Basic setup
|
|
--full Complete setup with all features
|
|
--ci Setup for CI/CD environments
|
|
```
|
|
|
|
### `deploy-docs.sh` - Deployment
|
|
```bash
|
|
./scripts/docs/deploy-docs.sh PLATFORM [OPTIONS]
|
|
|
|
PLATFORMS:
|
|
github-pages Deploy to GitHub Pages
|
|
netlify Deploy to Netlify
|
|
vercel Deploy to Vercel
|
|
custom Deploy to custom server
|
|
|
|
OPTIONS:
|
|
--domain D Custom domain
|
|
--token T Authentication token
|
|
```
|
|
|
|
## 🎯 Common Use Cases
|
|
|
|
### Logo Integration
|
|
```bash
|
|
# Add logos to cargo documentation
|
|
cargo doc --no-deps
|
|
./scripts/docs/enhance-docs.sh
|
|
|
|
# Build everything with logos
|
|
./scripts/docs/build-docs.sh --all
|
|
```
|
|
|
|
### Content Development
|
|
```bash
|
|
# Start development with live reload
|
|
./scripts/docs/docs-dev.sh --open
|
|
|
|
# Generate content from existing docs
|
|
./scripts/docs/generate-content.sh --sync
|
|
|
|
# Watch and rebuild on changes
|
|
./scripts/docs/build-docs.sh --watch
|
|
```
|
|
|
|
### CI/CD Integration
|
|
```bash
|
|
# Setup for continuous integration
|
|
./scripts/docs/setup-docs.sh --ci
|
|
|
|
# Build and deploy automatically
|
|
./scripts/docs/build-docs.sh --all
|
|
./scripts/docs/deploy-docs.sh github-pages --token $GITHUB_TOKEN
|
|
```
|
|
|
|
## 🚨 Troubleshooting
|
|
|
|
### Script Not Found
|
|
```bash
|
|
# Old path (DEPRECATED)
|
|
./scripts/build-docs.sh
|
|
|
|
# New path (CORRECT)
|
|
./scripts/docs/build-docs.sh
|
|
```
|
|
|
|
### Permission Denied
|
|
```bash
|
|
# Make scripts executable
|
|
chmod +x scripts/docs/*.sh
|
|
```
|
|
|
|
### Missing Dependencies
|
|
```bash
|
|
# Install required tools
|
|
./scripts/docs/setup-docs.sh --full
|
|
```
|
|
|
|
### Logo Enhancement Fails
|
|
```bash
|
|
# Ensure cargo doc was built first
|
|
cargo doc --no-deps
|
|
|
|
# Then enhance
|
|
./scripts/docs/enhance-docs.sh
|
|
```
|
|
|
|
## 📊 Output Locations
|
|
|
|
```
|
|
template/
|
|
├── book-output/ # mdBook output
|
|
│ └── html/ # Generated HTML files
|
|
├── target/doc/ # Cargo doc output
|
|
│ ├── server/ # Enhanced with logos
|
|
│ ├── client/ # Enhanced with logos
|
|
│ └── logos/ # Logo assets
|
|
└── dist/ # Combined for deployment
|
|
├── book/ # mdBook content
|
|
└── api/ # API documentation
|
|
```
|
|
|
|
## 🔗 Related Files
|
|
|
|
- **Main Config:** `book.toml` - mdBook configuration
|
|
- **Logo Assets:** `logos/` - Source logo files
|
|
- **Public Assets:** `public/logos/` - Web-accessible logos
|
|
- **Components:** `client/src/components/Logo.rs` - React logo components
|
|
- **Templates:** `docs/LOGO_TEMPLATE.md` - Logo usage templates
|
|
|
|
## 📞 Getting Help
|
|
|
|
```bash
|
|
# Show help for any script
|
|
./scripts/docs/SCRIPT_NAME.sh --help
|
|
|
|
# View comprehensive documentation
|
|
cat scripts/docs/README.md
|
|
|
|
# Check script status
|
|
./scripts/docs/build-docs.sh --version
|
|
```
|
|
|
|
## 🔄 Migration from Old Paths
|
|
|
|
If you have bookmarks or CI/CD scripts using old paths:
|
|
|
|
| Old Path | New Path |
|
|
|----------|----------|
|
|
| `./scripts/build-docs.sh` | `./scripts/docs/build-docs.sh` |
|
|
| `./scripts/enhance-docs.sh` | `./scripts/docs/enhance-docs.sh` |
|
|
| `./scripts/docs-dev.sh` | `./scripts/docs/docs-dev.sh` |
|
|
| `./scripts/setup-docs.sh` | `./scripts/docs/setup-docs.sh` |
|
|
| `./scripts/deploy-docs.sh` | `./scripts/docs/deploy-docs.sh` |
|
|
|
|
---
|
|
|
|
**Quick Tip:** Bookmark this file for fast access to documentation commands! 🔖 |