synapse-db

Documentation Overview

This document provides an overview of the Synapse DB documentation system.

Documentation Structure

Synapse DB has three types of documentation:

1. mdBook User Guide (book/)

Purpose: Comprehensive user-facing documentation Technology: mdBook Output: Static website at https://aaronberkhoff.github.io/synapse-db

Building

# Install mdBook
cargo install mdbook

# Build and serve with live reload
mdbook serve

# Build only
mdbook build

Contents

See book/README.md for details.

2. Rust API Documentation (cargo doc)

Purpose: Auto-generated API documentation from doc comments Technology: rustdoc Output: Integrated into mdBook at /api-docs/

Building

# Build API docs
cargo doc --no-deps --all-features

# Build and open in browser
cargo doc --no-deps --all-features --open

Writing Doc Comments

/// Short description of the function.
///
/// # Arguments
///
/// * `param` - Description of parameter
///
/// # Examples
///
/// ```
/// use synapse_db::Storage;
/// let storage = Storage::new();
/// ```
///
/// # Panics
///
/// When this function panics (if applicable)
///
/// # Errors
///
/// When this function returns an error (if applicable)
pub fn example_function(param: &str) -> Result<(), String> {
    // implementation
}

3. Inline Code Comments

Purpose: Explain complex code logic Guidelines:

Changelog Automation

Changelogs are automatically generated from git commits using git-cliff.

Configuration

Configured in cliff.toml

Generating Changelog

# Manual generation
./scripts/generate-changelog.sh

# Or directly
cargo install git-cliff
git-cliff --output CHANGELOG.md

Commit Message Format

Use Conventional Commits:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types:

Examples:

git commit -m "feat: add query caching"
git commit -m "fix: resolve memory leak in storage"
git commit -m "docs: update API documentation"
git commit -m "perf(query): optimize query execution"

Changelog Workflow

  1. Developers commit using conventional commits
  2. On release, run ./scripts/generate-changelog.sh
  3. Changelog is updated in:
    • CHANGELOG.md (root)
    • book/changelog.md (documentation)
  4. Commit and tag the release
  5. CI automatically publishes updated documentation

CI/CD Documentation Pipeline

Configured in .github/workflows/docs.yml

On Pull Request

  1. Build mdBook to verify no errors
  2. Build cargo doc to verify doc comments compile
  3. Check for broken links (best effort)
  4. Upload documentation artifact

On Push to Main

All the above, plus:

  1. Generate changelog from git history
  2. Deploy to GitHub Pages

Manual Trigger

You can manually trigger documentation builds via:

Documentation Workflow

Adding New Features

When adding a new feature:

  1. Write code with doc comments: 
    /// Description of new feature
pub fn new_feature() {}
  2. Update mdBook user guide:
    • Add page in book/ if major feature
    • Update existing page if enhancement
    • Add examples

  3. Update SUMMARY.md if you added new pages

  4. Update CHANGELOG.md manually or wait for auto-generation

  5. Test locally: 
    mdbook build
cargo doc
  6. Commit with conventional commit message: 
    git commit -m "feat: add awesome feature"

Updating Documentation

To update existing documentation:

  1. Edit markdown files in book/

  2. Preview changes: 
    mdbook serve
# Open http://localhost:3000
  3. Commit changes: 
    git commit -m "docs: update installation guide"
  4. CI will auto-deploy on merge to main

Documentation Best Practices

Writing Style

Organization

Code Examples

API Documentation

Tools and Dependencies

Required

Optional

File Organization

synapse-db/
├── book/                    # mdBook source
│   ├── SUMMARY.md          # Table of contents
│   ├── introduction.md     # Home page
│   ├── getting-started/    # Tutorial content
│   ├── guide/              # Feature guides
│   ├── api/                # API overview
│   ├── development/        # Contributing docs
│   ├── changelog.md        # Copy of root CHANGELOG.md
│   ├── faq.md
│   └── glossary.md
├── book.toml               # mdBook configuration
├── cliff.toml              # git-cliff configuration
├── CHANGELOG.md            # Generated changelog
├── CONTRIBUTING.md         # Contribution guide
├── DOCUMENTATION.md        # This file
├── README.md               # Project overview
├── src/                    # Rust code with doc comments
└── .github/
    └── workflows/
        └── docs.yml        # Documentation CI/CD

Viewing Documentation

Local Development

# User guide
mdbook serve
# Open http://localhost:3000

# API docs
cargo doc --open

Online

Troubleshooting

mdBook build fails

# Ensure mdBook is installed
cargo install mdbook

# Check for syntax errors in SUMMARY.md
mdbook build

# Clean and rebuild
mdbook clean
mdbook build

cargo doc fails

# Check for doc comment syntax errors
cargo doc

# Fix clippy warnings in doc comments
cargo clippy --all-targets

Changelog generation fails

# Ensure git-cliff is installed
cargo install git-cliff

# Check cliff.toml for syntax errors
git-cliff --output CHANGELOG.md

GitHub Pages not updating

Resources

Getting Help

Maintaining Documentation: Documentation is code. Keep it tested, reviewed, and updated just like your Rust code.

This site is open source. Improve this page.