documentation.md

Documentation

Documentation Structure

Neumann documentation consists of:

1. mdBook (docs/book/) - Conceptual docs, tutorials, operations
2. rustdoc - API reference generated from source
3. README.md per crate - Quick overview

Writing mdBook Pages

File Location

docs/book/src/
├── SUMMARY.md          # Table of contents
├── introduction.md     # Landing page
├── tutorials/          # Learning-oriented guides
├── how-to/             # Goal-oriented recipes
├── reference/          # Information-oriented tables
├── explanation/        # Understanding-oriented discussion
└── contributing/       # Contribution guides

Page Structure

# Page Title

Brief introduction (1-2 paragraphs).

## Section 1

Content with examples.

### Subsection

More detail.

## Section 2

Use tables for structured data:

| Column 1 | Column 2 |
|----------|----------|
| Value 1  | Value 2  |

Use mermaid for diagrams:

\`\`\`mermaid
flowchart LR
    A --> B --> C
\`\`\`

Admonitions

Use mdbook-admonish syntax:

```admonish note
This is a note.

This is a warning.

This is dangerous.

## Writing Rustdoc

### Module Documentation

```rust
//! # Module Name
//!
//! Brief description (one line).
//!
//! ## Overview
//!
//! Longer explanation of purpose and design decisions.
//!
//! ## Example
//!
//! ```rust
//! // Example code
//! ```

Type Documentation

/// Brief description of the type.
///
/// Longer explanation if needed.
///
/// # Example
///
/// ```rust
/// let value = MyType::new();
/// ```
pub struct MyType { ... }

When to Document

Document:

• All public types
• Non-obvious behavior
• Complex algorithms

Don't document:

• Self-explanatory methods (get, set, new)
• Trivial implementations

Building Documentation

mdBook

cd docs/book
mdbook build
mdbook serve  # Local preview at localhost:3000

rustdoc

cargo doc --workspace --no-deps --open

Full Build

# mdBook
cd docs/book && mdbook build

# rustdoc
cargo doc --workspace --no-deps

# Combine
cp -r target/doc docs/book-output/api/

Link Checking

cd docs/book
mdbook-linkcheck --standalone

Adding Mermaid Diagrams

Supported diagram types:

• flowchart - Flow diagrams
• sequenceDiagram - Sequence diagrams
• stateDiagram-v2 - State machines
• classDiagram - Class diagrams
• gantt - Gantt charts

Example:

\`\`\`mermaid
sequenceDiagram
    participant C as Client
    participant S as Server
    C->>S: Request
    S->>C: Response
\`\`\`