# Rustelo Documentation

<div align="center">
  <img src="logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
</div>

Welcome to the comprehensive documentation for Rustelo, a modular Rust web application template. This document serves as your gateway to understanding, setting up, and using all aspects of Rustelo.

## 📚 Documentation Overview

Rustelo provides multiple layers of documentation to serve different needs:

### 🎯 Quick References
- **[README.md](README.md)** - Main project overview and quick start
- **[FEATURES.md](FEATURES.md)** - Detailed feature documentation
- **[INSTALL.md](INSTALL.md)** - Installation guide

### 📖 Interactive Documentation (mdBook)
- **[Complete Guide](https://yourusername.github.io/rustelo)** - Full interactive documentation
- **Local Development**: `./scripts/docs-dev.sh` - Start local documentation server
- **Build Documentation**: `./scripts/build-docs.sh` - Build static documentation

### 📁 Documentation Directories
- **[docs/](docs/)** - Technical documentation and guides
- **[info/](info/)** - Implementation details and architectural decisions
- **[examples/](examples/)** - Usage examples and sample configurations

## 🚀 Getting Started with Documentation

### 1. Setup Documentation System
```bash
# Interactive setup (recommended)
./scripts/setup-docs.sh

# Full automated setup
./scripts/setup-docs.sh --full

# Minimal setup
./scripts/setup-docs.sh --minimal
```

### 2. Start Documentation Development
```bash
# Start local documentation server
./scripts/docs-dev.sh

# Or using just
just docs-dev
```

### 3. Build and Deploy
```bash
# Build documentation
./scripts/build-docs.sh

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

# Or using just
just docs-build
just docs-deploy-github
```

## 📋 Documentation Structure

### Core Sections

#### 🏁 Getting Started
- **[Quick Start](book/getting-started/quick-start.md)** - Get up and running in minutes
- **[Installation](book/getting-started/installation.md)** - Detailed installation guide
- **[Configuration](book/getting-started/configuration.md)** - Basic configuration
- **[Your First App](book/getting-started/first-app.md)** - Build your first application

#### 🎛️ Features
- **[Feature Overview](book/features/overview.md)** - All available features
- **[Authentication](book/features/authentication.md)** - User authentication system
- **[Content Management](book/features/content-management.md)** - Content management system
- **[Email System](book/features/email.md)** - Email functionality
- **[TLS Support](book/features/tls.md)** - HTTPS/TLS configuration
- **[Feature Combinations](book/features/combinations.md)** - How features work together

#### 🗄️ Database
- **[Database Overview](book/database/overview.md)** - Database system overview
- **[PostgreSQL Setup](book/database/postgresql.md)** - PostgreSQL configuration
- **[SQLite Setup](book/database/sqlite.md)** - SQLite configuration
- **[Database Configuration](book/database/configuration.md)** - Advanced configuration
- **[Migrations](book/database/migrations.md)** - Database migrations
- **[Database Abstraction](book/database/abstraction.md)** - Database abstraction layer

#### 🛠️ Development
- **[Development Setup](book/development/setup.md)** - Development environment
- **[Project Structure](book/development/structure.md)** - Understanding the codebase
- **[Development Workflow](book/development/workflow.md)** - Development best practices
- **[Testing](book/development/testing.md)** - Testing strategies
- **[Debugging](book/development/debugging.md)** - Debugging techniques
- **[Hot Reloading](book/development/hot-reloading.md)** - Development server setup

#### 🚀 Deployment
- **[Deployment Overview](book/deployment/overview.md)** - Deployment strategies
- **[Docker Deployment](book/deployment/docker.md)** - Containerized deployment
- **[Production Setup](book/deployment/production.md)** - Production configuration
- **[Environment-Specific Config](book/deployment/environments.md)** - Environment management
- **[Monitoring & Logging](book/deployment/monitoring.md)** - Observability

#### 🔒 Security
- **[Security Overview](book/security/overview.md)** - Security architecture
- **[Authentication Security](book/security/auth.md)** - Authentication security
- **[Data Protection](book/security/data-protection.md)** - Data encryption and protection
- **[CSRF Protection](book/security/csrf.md)** - CSRF prevention
- **[TLS Configuration](book/security/tls.md)** - TLS/SSL setup
- **[Security Best Practices](book/security/best-practices.md)** - Security guidelines

#### 🔧 API Reference
- **[API Overview](book/api/overview.md)** - API architecture
- **[Authentication Endpoints](book/api/auth.md)** - Authentication API
- **[Content Endpoints](book/api/content.md)** - Content management API
- **[Error Handling](book/api/errors.md)** - Error responses
- **[Rate Limiting](book/api/rate-limiting.md)** - Rate limiting configuration

## 🛠️ Documentation Tools

### Available Scripts
- **`./scripts/setup-docs.sh`** - Setup documentation system
- **`./scripts/docs-dev.sh`** - Start development server
- **`./scripts/build-docs.sh`** - Build documentation
- **`./scripts/deploy-docs.sh`** - Deploy documentation
- **`./scripts/generate-content.sh`** - Generate dynamic content

### Just Commands
```bash
# Documentation commands
just docs-setup          # Setup documentation system
just docs-dev            # Start development server
just docs-build          # Build documentation
just docs-build-sync     # Build with content sync
just docs-watch          # Watch for changes
just docs-deploy-github  # Deploy to GitHub Pages
just docs-deploy-netlify # Deploy to Netlify
just docs-deploy-vercel  # Deploy to Vercel
just docs-docker         # Build Docker image
just docs-generate       # Generate dynamic content
just docs-check-links    # Check for broken links
just docs-clean          # Clean build files
just docs-workflow       # Complete workflow
just help-docs           # Show documentation help
```

## 📖 Documentation Types

### 1. Technical Documentation (`docs/`)
Focused on implementation details and technical guides:
- **[2FA Implementation](docs/2fa_implementation.md)** - Two-factor authentication
- **[Database Configuration](docs/database_configuration.md)** - Database setup
- **[Email System](docs/email.md)** - Email configuration
- **[Encryption](docs/encryption.md)** - Data encryption
- **[Migration Guide](docs/database_migration_guide.md)** - Database migrations

### 2. Implementation Notes (`info/`)
Architectural decisions and implementation details:
- **[Feature System](info/feature_system.md)** - Feature architecture
- **[Database Abstraction](info/database_abstraction.md)** - Database design
- **[Authentication](info/auth_readme.md)** - Authentication system
- **[Configuration](info/config.md)** - Configuration system
- **[Deployment](info/deployment.md)** - Deployment strategies

### 3. Interactive Documentation (`book/`)
Comprehensive user-friendly guides built with mdBook:
- Searchable content
- Mobile-friendly design
- Cross-referenced sections
- Code examples with syntax highlighting
- Print-friendly format

## 🌐 Deployment Options

### GitHub Pages
```bash
# Automatic deployment via GitHub Actions
./scripts/deploy-docs.sh github-pages

# Manual deployment
just docs-deploy-github
```

### Netlify
```bash
# Deploy to Netlify
./scripts/deploy-docs.sh netlify
just docs-deploy-netlify
```

### Vercel
```bash
# Deploy to Vercel
./scripts/deploy-docs.sh vercel
just docs-deploy-vercel
```

### Docker
```bash
# Build documentation container
./scripts/deploy-docs.sh docker
just docs-docker

# Run documentation server
docker run -p 8080:80 rustelo-docs:latest
```

### AWS S3
```bash
# Deploy to S3 (requires AWS_S3_BUCKET)
export AWS_S3_BUCKET=your-bucket-name
./scripts/deploy-docs.sh aws-s3
```

## 🔄 CI/CD Integration

### GitHub Actions
Automatic documentation builds and deployments:
- **Build on PR**: Validates documentation builds
- **Deploy on merge**: Automatically deploys to GitHub Pages
- **Link checking**: Validates all links in documentation
- **Multi-format build**: Builds HTML, PDF, and EPUB formats

### Setup CI/CD
```bash
# Setup CI/CD integration
./scripts/setup-docs.sh --ci

# This creates:
# - .github/workflows/docs.yml
# - Automated deployment configuration
# - Link checking integration
```

## 📱 Mobile-Friendly Features

- **Responsive Design**: Works on all screen sizes
- **Touch Navigation**: Mobile-friendly navigation
- **Offline Support**: Progressive web app features
- **Fast Loading**: Optimized for mobile connections
- **Search**: Full-text search functionality

## 🎨 Customization

### Custom Styling
- **`book/theme/custom.css`** - Custom styles
- **`book/theme/custom.js`** - Custom JavaScript
- **Brand colors and fonts**
- **Custom layouts and components**

### Content Organization
- **Modular structure**: Easy to reorganize content
- **Cross-references**: Automatic link generation
- **Content templates**: Consistent formatting
- **Dynamic content**: Auto-generated sections

## 🔍 Search and Discovery

### Built-in Search
- **Full-text search**: Search across all documentation
- **Instant results**: Fast search with highlighting
- **Keyboard shortcuts**: `Ctrl+K` or `Cmd+K` to search
- **Search suggestions**: Auto-complete functionality

### Navigation
- **Hierarchical structure**: Logical content organization
- **Breadcrumbs**: Easy navigation context
- **Previous/Next**: Sequential navigation
- **Table of contents**: Section overview

## 📊 Analytics and Monitoring

### Documentation Metrics
- **Build times**: Monitor documentation build performance
- **Broken links**: Automatic link validation
- **Usage analytics**: Track documentation usage (when deployed)
- **Performance monitoring**: Page load times and optimization

### Quality Assurance
- **Link checking**: Automated broken link detection
- **Content validation**: Ensure all sections are complete
- **Style checking**: Consistent formatting
- **Accessibility testing**: WCAG compliance

## 🤝 Contributing to Documentation

### How to Contribute
1. **Edit content**: Modify files in `book/` directory
2. **Test locally**: Run `just docs-dev` to preview changes
3. **Submit PR**: Create pull request with documentation changes
4. **Review process**: Automated checks and manual review

### Content Guidelines
- **Clear writing**: Use simple, clear language
- **Code examples**: Include working code examples
- **Screenshots**: Add visual aids when helpful
- **Cross-references**: Link to related sections
- **Consistency**: Follow established patterns

### Content Types
- **Tutorials**: Step-by-step guides
- **Reference**: API and configuration documentation
- **Examples**: Code samples and use cases
- **Troubleshooting**: Common issues and solutions

## 🆘 Getting Help

### Documentation Issues
- **[GitHub Issues](https://github.com/yourusername/rustelo/issues)** - Report documentation bugs
- **[Discussions](https://github.com/yourusername/rustelo/discussions)** - Ask questions
- **[Contributing Guide](book/contributing/docs.md)** - How to contribute

### Quick Help
```bash
# Show all documentation commands
just help-docs

# Check documentation build
just docs-build

# Start local development
just docs-dev
```

## 🎯 Next Steps

1. **[Setup Documentation](scripts/setup-docs.sh)** - Initialize your documentation system
2. **[Start Development](scripts/docs-dev.sh)** - Begin working with documentation
3. **[Deploy Documentation](scripts/deploy-docs.sh)** - Share your documentation
4. **[Customize Experience](book/theme/)** - Make it your own

---

**Happy documenting!** 📚✨

The Rustelo documentation system is designed to grow with your project. Start simple, add complexity as needed, and maintain comprehensive documentation that serves your users and contributors effectively.

For the most up-to-date documentation, visit: **[https://yourusername.github.io/rustelo](https://yourusername.github.io/
