Rustelo/scripts/docs/QUICK_REFERENCE.md

# 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! 🔖