Embedding Figures in Docs

---
count: false
class: nord-dark, middle, center

# 🖼️ Embedding Figures in Docs

### Python 🐍 vs Rust 🦀

@luk036 👨‍💻 · 2026 📅

---

### 📋 Agenda

**1. The Problem** 🤔
- Why Figures Are Essential
- The Asset Pipeline Gap
- Real-World Impact

**2. Python Solutions** 🐍
- `.. figure::` — static images
- `.. plot::` — auto-generated plots
- `.. svgbob::` — ASCII diagrams
- `.. math::` — equations
]

**3. Rust Solutions** 🦀
- `embed-doc-image` — static images
- `svgbob` — ASCII diagrams
- `$$...$$` — equations

**4. Feature Comparison** ⚡
- Side-by-side per feature
- Architecture diagram
- Key Takeaways & Q&A
]

---

### 🤔 The Problem

Mathematical & geometric libraries cry out for **visual documentation**:

```python
def halton(n, base1, base2):
    """Generate 2D Halton sequence points."""
    ...
```

```rust
/// Halton sequence generator (bases 2, 3).
pub struct Halton { ... }
```

❌ **Without figures**: Users must imagine the distribution
✅ **With figures**: A scatter plot tells the story instantly

**Core issue**: Neither Sphinx nor rustdoc natively bundles local image files into the published documentation output.

**Python has mature solutions** across the board. **Rust** is catching up — but still has gaps.

---

### 📋 Feature Overview

**Python (Sphinx)** 🐍

.font-sm.mb-xs[
| Feature | Status |
|---------|--------|
| Static images | ✅ Native `.. figure::` |
| Auto-generated plots | ✅ `.. plot::` directive |
| ASCII→SVG diagrams   | ✅ `.. svgbob::`    |
| Equations | ✅ `.. math::` / `:math:` |
| Asset pipeline | ✅ Built-in auto-copy |
| Hosted (RTD) | ✅ Works out of box |
]
]
.pull-right[

**Rust (rustdoc)** 🦀

.font-sm.mb-xs[
| Feature | Status |
|---------|--------|
| Static images | ❌ No native asset bundling |
| Auto-generated plots | ❌ Not available |
| ASCII→SVG diagrams   | ✅ `svgbob` crate     |
| Equations | ✅ `$$...$$` inline |
| Asset pipeline | ⚠️ `embed-doc-image` (workaround) |
| Hosted (docs.rs) | ⚠️ Needs `doc-images` feature |
]
]

---

### 🖼️ The Asset Pipeline Gap

**Local build** — seems to work:

```text
# Sphinx                          # rustdoc
docs/_build/html/                 target/doc/my_crate/
├── index.html                    ├── index.html
├── _images/                      ├── images/halton.png
│   └── halton.png                └── ...
└── ...
```

**Published** — images go missing 😱

- **docs.rs** publishes only what `cargo doc` produces — **no asset bundling**
- **ReadTheDocs** copies `_images/` for Sphinx-managed figures — **works correctly**
- Neither tool knows: *"this image is a documentation asset"*

**Python solves this natively** (Sphinx asset pipeline). **Rust** needs a crate.

---

### 💥 Real-World Impact

**Rust projects affected:**

| Domain | Examples |
|--------|----------|
| GUI     | egui, Masonry, Slint |
| Math    | nalgebra, lds-rs |
| Plotting | plotters, plotly |
| Science | rust-cv, ndarray-stats |

**Quote from Masonry devs (2024):**
> *"We considered a LOT of alternatives... all of them were pretty fragile. We ultimately decided not to include all images."*
]

**Python projects — no problem:**

| Domain | Examples |
|--------|----------|
| Math    | numpy, scipy, lds-gen |
| Optim.  | cvxpy, ellalgo |
| Science | biopython, astropy |
| EDA     | netlistx, physdes-py |

**Sphinx ecosystem** handles images, figures, equations, and diagrams — all natively, all work on ReadTheDocs.
]

---

## 🐍 Python vs 🦀 Rust — Feature by Feature

---

### 🖼️ Static Images

**Python (Sphinx)** 🐍

```rst
.. figure:: images/halton.png
   :width: 400px
   :alt: Halton 2D scatter

500 Halton points.
```

✅ Native directive `.. figure::`
✅ Auto-copies to `_images/` in output
✅ Rewrites HTML paths
✅ RTD = works
✅ Zero extra dependencies

**How**: Sphinx detects the directive, copies the file, rewrites the path. All built-in.
]

**Rust (rustdoc)** 🦀

```rust
//! ![Scatter][plot]
//! 500 Halton points.

#![cfg_attr(feature = "doc-images",
    doc = embed_doc_image::embed_image!(
        "plot", "docs/images/plot.png"
    )
)]
```

❌ No native image bundling
❌ Requires external crate
❌ Requires proc macro
❌ Base64 bloat in HTML
⚠️ docs.rs works with feature flag

**How**: `embed-doc-image` base64-encodes the PNG into a `data:` URI at compile time.
]

---

### 📈 Auto-Generated Plots

**Python (Sphinx)** 🐍

```rst
.. plot::

import matplotlib.pyplot as plt
   from lds_gen.lds import Halton

pts = Halton(base=[2,3]).pop_batch(500)
   plt.scatter(*zip(*pts))
```

✅ Code runs at doc-build time
✅ PNG captured and embedded
✅ Never stale — code IS the figure
✅ External script or inline code
✅ `matplotlib.sphinxext.plot_directive`

**Pipeline**: Source → `sphinx-build` → execute Python → capture PNG → embed in HTML.
]

**Rust (rustdoc)** 🦀

```rust
// No equivalent.
// Must pre-generate PNGs
// separately (e.g. Python script)
// and embed them as static images.
```

❌ No `.. plot::` equivalent
❌ No eval-at-doc-build-time
❌ Must maintain separate script
❌ Must commit PNGs to repo
❌ Or embed via `embed-doc-image`

**Rust has no macro or tool** to run code and capture output during `cargo doc`.
]

---

### 🎨 ASCII → SVG Diagrams

**Python (Sphinx)** 🐍

```rst
.. svgbob::
   :align: center

_.-'''''''-._
    ,'    |        `.
   /      |          \
   |      | .         |
   |      |           |
    \     |          /
     `._  |       _.'
        '-......-'
```

✅ ASCII art → inline SVG
✅ `sphinxcontrib-svgbob` extension
✅ No image files to manage
✅ Renders in RTD
]

**Rust (svgbobdoc)** 🦀

```rust
#[doc = svgbobdoc::transform!(
/// ```svgbob
///   _.-'''''''-._
/// ,'    |        `.
/// ```
)]
pub struct MyStruct;
```

✅ `svgbobdoc` crate (proc macro)
✅ ` ```svgbob ` code fence in doc comments
✅ SVG embedded at compile time via `transform!`
✅ docs.rs compatible
✅ 1.6M+ downloads

**Rust uses the `svgbobdoc` crate** — a proc-macro that converts ASCII diagrams to inline SVG at compile time.
]

---

### 🦀 Rust `svgbobdoc` — Setup

**1. Add to `Cargo.toml`:**

```toml
[dependencies]
svgbobdoc = { version = "0.2", features = ["enable"] }
```

<pre>
use svgbobdoc::transform;

#[doc = transform!(
/// # My Struct
///
/// ```svgbob
///  .--------------------.
///  |   ASCII diagram    |
///  `--------------------'
/// ```
)]
pub struct MyStruct;
```
</pre>
]
.pull-right[
**3. Feature-gating** (optional, saves compile time):

```toml
[features]
doc-svg = ["svgbobdoc/enable"]
```

The `enable` feature turns on `svgbob` rendering. Without it, the macro is a no-op.

]

---

### 📐 Equations

**Python (Sphinx)** 🐍

```rst
.. math::

\phi_b(n) =
   \sum_{k=0}^{m} \frac{d_k}{b^{k+1}}
```

```rst
Inline :math:`\phi_2(n)` works too.
```

✅ `.. math::` display equations
✅ `:math:` inline equations
✅ MathJax or imgmath backends
✅ ReadTheDocs compatible
]

**Rust (rustdoc)** 🦀

```rust
//! Display:
//! $$ \phi_b(n) = \sum_{k=0}^{m} \frac{d_k}{b^{k+1}} $$
//!
//! Inline: $ \phi_2(n) $
```

✅ `$$...$$` display equations
✅ `$...$` inline equations
✅ KaTeX rendered
✅ docs.rs compatible
✅ Markdown-native syntax

**Rust matches Python here** — rustdoc has had KaTeX math support since 2023.
]

---

### 📦 Asset Pipeline

**Sphinx automatically:**
- Copies `images/` to `_images/` in output
- Detects assets referenced in directives
- Rewrites HTML paths
- Works on RTD without extra config
]

**`cargo doc` does NOT:**
- Copy any files outside `src/`
- Know about documentation assets
- Bundle images for docs.rs

**Workaround**: `embed-doc-image` base64-encodes at compile time.
]

---

### ⚡ Architecture

.mermaid[
<pre>
graph TD
    subgraph "Python (Sphinx)"
        A1["conf.py\nextensions"] --> B1["sphinx-build"]
        C1["images/"] -->|"auto-copy"| B1
        D1["*.rst: .. figure::"] --> B1
        E1["*.rst: .. plot::"] -->|"matplotlib execute"| B1
        F1["*.rst: .. svgbob::"] -->|"ASCII→SVG"| B1
        B1 --> G1["HTML + _images/\non ReadTheDocs"]
    end

subgraph "Rust (rustdoc)"
        A2["Cargo.toml\nfeatures"] --> B2["cargo doc"]
        C2["lib.rs\nembed_image!"] -->|"base64 encode"| B2
        D2["pre-rendered\nPNG files"] --> C2
        E2["lib.rs\n```svgbob"] -->|"ASCII→SVG"| B2
        B2 --> F2["HTML with\ndata: URIs\non docs.rs"]
    end

style A1 fill:#e8f5e9,stroke:#2e7d32
    style D1 fill:#e3f2fd,stroke:#1565c0
    style E1 fill:#c8e6c9,stroke:#2e7d32
    style F1 fill:#fff9c4,stroke:#f9a825
    style G1 fill:#fff3e0,stroke:#e65100
    style A2 fill:#e8f5e9,stroke:#2e7d32
    style C2 fill:#e3f2fd,stroke:#1565c0
    style E2 fill:#fff9c4,stroke:#f9a825
    style F2 fill:#fff3e0,stroke:#e65100
</pre>
]

**Python**: Native tools — files copied, code executed, ASCII converted. All built into Sphinx.
**Rust**: Same features via crates — `embed-doc-image` for images, `svgbob` for diagrams.

---

### ⚠️ Pitfalls Side-by-Side

**Python (Sphinx)**

1. **`html_static_path` config**
   - Must include image directories

2. **Path resolution**
   - Relative: `images/plot.png`
   - Absolute: `/images/plot.png`

3. **`.. plot::` dependencies**
   - Needs matplotlib at build time
   - Code must be importable

4. **RST verbosity**
   - Directives more verbose than Markdown
]

**Rust (rustdoc)**

1. **Missing images → compile error**
   ```
   error: proc macro panicked
   message: Failed to load image
   ```

2. **Base64 bloat**
   - 100 KB PNG → ~133 KB in HTML
   - Optimize with `oxipng` / `pngquant`

3. **Feature-gating complexity**
   - `cfg_attr(feature = "doc-images", ...)`
   - Inner attributes need nightly

4. **No auto-generated plots**
   - Every plot must be pre-rendered externally
   - No eval-at-doc-build-time
]

---

### 📊 Results: Four Python Projects

| Project | Plots | svgbob | Domain |
|---------|-------|-----------|--------|
| `lds-gen`    | 4 | ✅ 3 diagrams | Low-discrepancy sequences |
| `netlistx`   | 2 | —           | Netlist algorithms |
| `physdes-py` | 5 | ✅ docstrings | Physical design |
| `ellalgo`    | 2 | ✅ docstrings | Ellipsoid method |
| **Total**    | **13** | **All zero warnings** ✅ | |

**Setup cost per project:**
- Static images: 0 lines (Sphinx built-in)
- `.. plot::`: +5 lines in `conf.py`
- `.. svgbob::` : +1 line in `conf.py`

**Maintenance**: Change source → rebuild → docs update. That's it.

---

### 💡 Key Takeaways

**Python (Sphinx)** — Mature ecosystem ✅

| Need | Solution | Lines |
|------|----------|-------|
| Static image | `.. figure::` | 0 |
| Auto plot | `.. plot::` | +1 ext |
| ASCII diagram | `.. svgbob::` | +1 ext |
| Equation | `.. math::` | 0 |
| Asset pipeline | Auto-copy | 0 |

**All work on ReadTheDocs. All zero extra runtime deps.**
]

**Rust (rustdoc)** — Catching up 🛠️

| Need | Solution | Lines |
|------|----------|-------|
| Static image | `embed-doc-image` | 6+20 |
| Auto plot | ❌ Not available | Pre-render externally |
| ASCII diagram | `svgbob` crate | 0 (built-in) |
| Equation | `$$...$$` | 0 |
| Asset pipeline | `embed-doc-image` | Same |

**Rust's `svgbob` gives parity for diagrams. Image bundling still needs a crate.**
]

---

### 📈 Future: Rust RFC #3397

**Proposal**: Native asset bundling in rustdoc

```rust
//! This would be the dream:
//!
//! ![Scatter](docs/images/plot.png)
//!
//! cargo doc automatically copies
//! docs/ to output
```

**Status**: On hold — blocked on `cargo` source format evolution
**Tracking**: [github.com/rust-lang/rfcs/issues/3397](https://github.com/rust-lang/rfcs/issues/3397)

**Python has had this for 20+ years. Rust will get there too.**

---

## ❓ Questions?

---

# 🙏 Thank You

### Document with Pictures! 🖼️

**Key crates**:
- [`embed-doc-image`](https://crates.io/crates/embed-doc-image)

**Repositories**:
- [`github.com/luk036/lds-rs`](https://github.com/luk036/lds-rs)
- [`github.com/luk036/lds-gen`](https://github.com/luk036/lds-gen) (Python)
- [`github.com/luk036/netlistx`](https://github.com/luk036/netlistx)
- [`github.com/luk036/physdes-py`](https://github.com/luk036/physdes-py)
- [`github.com/luk036/ellalgo`](https://github.com/luk036/ellalgo)

@luk036 👨‍💻 · 2026 📅