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)

//! <img src="https://raw.githubusercontent.com/yourusername/rustelo/main/logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />

After (Relative Paths)

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

./scripts/build-docs.sh

Using Just

just docs-cargo

Using Cargo Directly

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

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

//! <img src="../logos/rustelo_dev-logo-v.svg" alt="RUSTELO" width="200" />

Dark Theme Logo

//! <img src="../logos/rustelo_dev-logo-b-h.svg" alt="RUSTELO" width="300" />

Icon Logo for Inline Use

//! <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:

[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:

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