Rustelo/scripts/docs/README.md

# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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**
   ```bash
   # Check mdBook installation
   mdbook --version
   
   # Reinstall if needed
   cargo install mdbook --force
   ```

2. **Cargo doc enhancement fails**
   ```bash
   # Ensure cargo doc was built first
   cargo doc --no-deps
   
   # Check script permissions
   chmod +x ./enhance-docs.sh
   ```

3. **Deployment fails**
   ```bash
   # Check environment variables
   echo $GITHUB_TOKEN
   
   # Verify repository permissions
   git remote -v
   ```

4. **Logo files missing**
   ```bash
   # Ensure logos are in the correct location
   ls -la logos/
   ls -la public/logos/
   ```

### Debug Mode
Most scripts support debug mode for troubleshooting:
```bash
# 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](../../book/developers/brand/logo-usage.md)** - How to use logos in documentation
- **[mdBook Configuration](../../book.toml)** - mdBook setup and configuration
- **[Deployment Guide](../../book/deployment/)** - Platform-specific deployment guides
- **[Contributing Guidelines](../../CONTRIBUTING.md)** - 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)*