Rustelo/scripts/docs

Documentation Scripts

This directory contains all scripts related to building, managing, and deploying documentation for the Rustelo project.

📁 Scripts Overview

🔨 Build Scripts

build-docs.sh

Purpose: Comprehensive documentation build system
Description: Builds both mdBook and cargo documentation with logo integration

Usage:

# Build mdBook documentation only
./build-docs.sh

# Build cargo documentation with logos
./build-docs.sh --cargo

# Build all documentation (mdBook + cargo doc)
./build-docs.sh --all

# Serve documentation locally
./build-docs.sh --serve

# Watch for changes and rebuild
./build-docs.sh --watch

# Sync existing docs into mdBook format
./build-docs.sh --sync

Features:

• Builds mdBook documentation
• Generates cargo doc with logo enhancement
• Serves documentation locally
• Watches for file changes
• Syncs existing documentation
• Provides build metrics

enhance-docs.sh

Purpose: Add Rustelo branding to cargo doc output
Description: Post-processes cargo doc HTML files to add logos and custom styling

Usage:

# Enhance cargo doc with logos
./enhance-docs.sh

# Clean up backup files
./enhance-docs.sh --clean

# Restore original documentation
./enhance-docs.sh --restore

Features:

• Adds logos to all crate documentation pages
• Injects custom CSS for branding
• Creates backup files for safety
• Adds footer with project links
• Supports restoration of original files

🌐 Development Scripts

docs-dev.sh

Purpose: Start development server for documentation
Description: Launches mdBook development server with live reload

Usage:

# Start development server
./docs-dev.sh

# Start with specific port
./docs-dev.sh --port 3001

# Start and open browser
./docs-dev.sh --open

Features:

• Live reload on file changes
• Automatic browser opening
• Custom port configuration
• Hot reloading for rapid development

⚙️ Setup Scripts

setup-docs.sh

Purpose: Initialize documentation system
Description: Sets up the complete documentation infrastructure

Usage:

# Basic setup
./setup-docs.sh

# Full setup with all features
./setup-docs.sh --full

# Setup with content generation
./setup-docs.sh --generate

# Setup for specific platform
./setup-docs.sh --platform github-pages

Features:

• Installs required tools (mdBook, etc.)
• Creates directory structure
• Generates initial content
• Configures theme and styling
• Platform-specific optimization

generate-content.sh

Purpose: Generate documentation content
Description: Creates documentation pages from templates and existing content

Usage:

# Generate all content
./generate-content.sh

# Generate specific section
./generate-content.sh --section features

# Generate from existing docs
./generate-content.sh --sync

# Force regeneration
./generate-content.sh --force

Features:

• Converts existing documentation
• Generates API documentation
• Creates navigation structure
• Processes templates
• Validates content structure

🚀 Deployment Scripts

deploy-docs.sh

Purpose: Deploy documentation to various platforms
Description: Automated deployment of built documentation

Usage:

# Deploy to GitHub Pages
./deploy-docs.sh github-pages

# Deploy to Netlify
./deploy-docs.sh netlify

# Deploy to custom server
./deploy-docs.sh custom --server example.com

# Deploy with custom domain
./deploy-docs.sh github-pages --domain docs.rustelo.dev

Supported Platforms:

• GitHub Pages
• Netlify
• Vercel
• AWS S3
• Custom servers via SSH

Features:

• Platform-specific optimization
• Custom domain configuration
• SSL certificate handling
• Automated builds
• Rollback capabilities

🔄 Workflow Examples

Complete Documentation Build

# 1. Setup documentation system
./setup-docs.sh --full

# 2. Generate content from existing docs
./generate-content.sh --sync

# 3. Build all documentation
./build-docs.sh --all

# 4. Deploy to GitHub Pages
./deploy-docs.sh github-pages

Development Workflow

# 1. Start development server
./docs-dev.sh --open

# 2. In another terminal, watch for cargo doc changes
cargo watch -x "doc --no-deps" -s "./enhance-docs.sh"

# 3. Make changes and see live updates

CI/CD Integration

# Automated build and deploy (for CI/CD)
./setup-docs.sh --ci
./build-docs.sh --all
./deploy-docs.sh github-pages --token $GITHUB_TOKEN

📋 Prerequisites

Required Tools

• mdBook - cargo install mdbook
• Rust/Cargo - For cargo doc generation
• Git - For deployment to GitHub Pages

Optional Tools

• mdbook-linkcheck - cargo install mdbook-linkcheck
• mdbook-toc - cargo install mdbook-toc
• mdbook-mermaid - cargo install mdbook-mermaid
• cargo-watch - cargo install cargo-watch

Environment Variables

# For deployment
export GITHUB_TOKEN="your-github-token"
export NETLIFY_AUTH_TOKEN="your-netlify-token"
export VERCEL_TOKEN="your-vercel-token"

# For custom domains
export DOCS_DOMAIN="docs.rustelo.dev"
export CNAME_RECORD="rustelo.github.io"

📁 Output Structure

template/
├── book-output/           # mdBook output
│   ├── html/             # Generated HTML
│   └── index.html        # Main documentation entry
├── target/doc/           # Cargo doc output
│   ├── server/           # Server crate docs
│   ├── client/           # Client crate docs
│   ├── shared/           # Shared crate docs
│   └── logos/            # Logo assets
└── docs-dist/            # Combined distribution
    ├── book/             # mdBook content
    ├── api/              # API documentation
    └── assets/           # Static assets

🔧 Configuration

mdBook Configuration

File: book.toml

• Theme customization
• Logo integration
• Plugin configuration
• Build settings

Script Configuration

File: scripts/docs/config.sh (if exists)

• Default deployment platform
• Custom domain settings
• Build optimization flags
• Platform-specific options

🐛 Troubleshooting

Common Issues

1. mdBook build fails

   # Check mdBook installation
   mdbook --version
   
   # Reinstall if needed
   cargo install mdbook --force
   

2. Cargo doc enhancement fails

   # Ensure cargo doc was built first
   cargo doc --no-deps
   
   # Check script permissions
   chmod +x ./enhance-docs.sh
   

3. Deployment fails

   # Check environment variables
   echo $GITHUB_TOKEN
   
   # Verify repository permissions
   git remote -v
   

4. Logo files missing

   # Ensure logos are in the correct location
   ls -la logos/
   ls -la public/logos/
   

Debug Mode

Most scripts support debug mode for troubleshooting:

# Enable debug output
DEBUG=1 ./build-docs.sh --all

# Verbose logging
VERBOSE=1 ./deploy-docs.sh github-pages

📊 Metrics and Analytics

Build Metrics

• Total pages generated
• Build time
• File sizes
• Link validation results

Deployment Metrics

• Deployment time
• File transfer size
• CDN cache status
• Performance scores

🔒 Security

Best Practices

• Use environment variables for sensitive data
• Validate all input parameters
• Create backups before destructive operations
• Use secure protocols for deployments

Token Management

• Store tokens in secure environment variables
• Use minimal required permissions
• Rotate tokens regularly
• Monitor token usage

🤝 Contributing

Adding New Scripts

1. Follow naming convention: action-target.sh
2. Include help text and usage examples
3. Add error handling and validation
4. Update this README
5. Test with different configurations

Modifying Existing Scripts

1. Maintain backward compatibility
2. Update documentation
3. Test all use cases
4. Verify CI/CD integration

📚 Related Documentation

• Logo Usage Guide - How to use logos in documentation
• mdBook Configuration - mdBook setup and configuration
• Deployment Guide - Platform-specific deployment guides
• Contributing Guidelines - How to contribute to documentation

📞 Support

For issues with documentation scripts:

1. Check this README for common solutions
2. Review script help text: ./script-name.sh --help
3. Enable debug mode for detailed output
4. Open an issue on GitHub with logs and configuration

---

Generated by Rustelo Documentation System
Last updated: $(date)