Rustelo/docs/cargo_docs.md

# Cargo Documentation Setup

This document explains how the RUSTELO project's cargo documentation is configured to work with logo assets and relative paths.

## Overview

The RUSTELO project uses relative paths for logo references in cargo documentation comments (rustdoc). This ensures that logos display correctly in generated documentation while maintaining portability and avoiding hardcoded GitHub URLs.

## Logo Path Configuration

### Before (Absolute URLs)
```rust
//! <img src="https://raw.githubusercontent.com/yourusername/rustelo/main/logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
```

### After (Relative Paths)
```rust
//! <img src="../logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
```

## Documentation Structure

```
template/
├── logos/                          # Logo assets directory
│   ├── rustelo_dev-logo-h.svg     # Horizontal logo
│   ├── rustelo_dev-logo-v.svg     # Vertical logo
│   ├── rustelo_dev-logo-b-h.svg   # Black horizontal logo
│   ├── rustelo_dev-logo-b-v.svg   # Black vertical logo
│   └── rustelo-imag.svg           # Icon logo
├── target/doc/                     # Generated documentation
│   ├── logos/                      # Copied logo assets
│   ├── client/                     # Client crate docs
│   ├── server/                     # Server crate docs
│   └── shared/                     # Shared crate docs
└── scripts/
    └── build-docs.sh               # Documentation build script
```

## Building Documentation

### Using the Build Script
```bash
./scripts/build-docs.sh
```

### Using Just
```bash
just docs-cargo
```

### Using Cargo Directly
```bash
cargo doc --no-deps --lib --workspace
cp -r logos target/doc/
```

## Build Script Features

The `scripts/build-docs.sh` script provides:

- **Automatic Asset Copying**: Copies logo assets to the documentation output directory
- **Clean Builds**: Removes previous documentation before building
- **Error Handling**: Comprehensive error checking and colored output
- **Verification**: Confirms that assets were copied successfully
- **Multiple Options**: Supports various documentation build configurations

## Logo Usage in Documentation

### Standard Header Logo
```rust
//! # Crate Name
//!
//! <div align="center">
//!   <img src="../logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
//! </div>
//!
//! Description of the crate...
```

### Vertical Logo for Compact Displays
```rust
//! <img src="../logos/rustelo_dev-logo-v.svg" alt="RUSTELO" width="200" />
```

### Dark Theme Logo
```rust
//! <img src="../logos/rustelo_dev-logo-b-h.svg" alt="RUSTELO" width="300" />
```

### Icon Logo for Inline Use
```rust
//! <img src="../logos/rustelo-imag.svg" alt="RUSTELO" width="24" height="24" />
```

## Path Resolution

The relative paths work because:

1. **Crate Documentation**: Generated in `target/doc/[crate_name]/`
2. **Logo Assets**: Copied to `target/doc/logos/`
3. **Relative Path**: `../logos/` goes up one directory from the crate to the doc root

## Integration with Cargo.toml

Each crate's `Cargo.toml` includes documentation metadata:

```toml
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
```

## Automated Workflow

### Development Workflow
1. Write rustdoc comments with relative logo paths
2. Run `just docs-cargo` to build documentation with assets
3. Open `target/doc/index.html` to view results

### CI/CD Integration
The build script can be integrated into CI/CD pipelines:

```yaml
- name: Build Documentation
  run: ./scripts/build-docs.sh

- name: Deploy Documentation
  run: |
    # Deploy target/doc/ directory to hosting service
```

## Troubleshooting

### Logo Not Displaying
- Ensure `logos/` directory exists in project root
- Verify the build script ran successfully
- Check that `target/doc/logos/` contains the logo files

### Path Issues
- Confirm relative paths use `../logos/` format
- Verify the logo filename matches exactly (case-sensitive)
- Check that the build script has execute permissions

### Build Failures
- Run `cargo clean` before building documentation
- Ensure all dependencies are installed
- Check for syntax errors in rustdoc comments

## Best Practices

### Documentation Comments
- Always include `alt` attributes for accessibility
- Use consistent logo sizing across crates
- Include proper HTML structure with `<div align="center">`

### Asset Management
- Keep logo files in the root `logos/` directory
- Use descriptive filenames for different logo variants
- Maintain consistent aspect ratios

### Build Process
- Always use the build script for documentation generation
- Verify assets are copied after each build
- Test documentation locally before deploying

## File Locations

### Updated Files
- `template/client/src/lib.rs` - Client crate documentation
- `template/server/src/lib.rs` - Server crate documentation
- `template/server/src/main.rs` - Server binary documentation
- `template/shared/src/lib.rs` - Shared crate documentation
- `template/docs/LOGO_TEMPLATE.md` - Logo usage templates

### Created Files
- `template/scripts/build-docs.sh` - Documentation build script
- `template/docs/CARGO_DOCS.md` - This documentation file

### Modified Files
- `template/justfile` - Added `docs-cargo` command

## Version Information

This setup is compatible with:
- **Rust**: 1.87.0+
- **Cargo**: 1.87.0+
- **rustdoc**: Standard with Rust installation

## Support

For questions or issues related to the documentation setup:

1. Check the build script output for error messages
2. Verify all logo files exist in the `logos/` directory
3. Ensure the build script has execute permissions
4. Test with a clean build using `cargo clean`

## Example Output

When the build script runs successfully, you should see:

```
[INFO] Building RUSTELO documentation with logo assets...
[INFO] Cleaning previous documentation...
[INFO] Generating cargo documentation...
[INFO] Documentation generated successfully
[INFO] Copying logo assets to documentation output...
[INFO] Logo assets copied to target/doc/logos/
[INFO] Logo assets verified in documentation output
[INFO] Documentation build complete!
```

The generated documentation will be available at `target/doc/index.html` with all logos properly displaying.