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

# 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

# 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

# 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

./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

./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

./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

./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

./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

# 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

# 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

# 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

# Old path (DEPRECATED)
./scripts/build-docs.sh

# New path (CORRECT)
./scripts/docs/build-docs.sh

Permission Denied

# Make scripts executable
chmod +x scripts/docs/*.sh

Missing Dependencies

# Install required tools
./scripts/docs/setup-docs.sh --full

Logo Enhancement Fails

# 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

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