Skip to content

Commit 8e22bc8

Browse files
MohammadRazieiMohammadRaziei
committed
feat(docs): add Python API documentation and examples
Add comprehensive documentation for the Python API, including: - `mmdr.render()` function with parameters and examples - `Diagram` class with methods and usage examples - Batch rendering examples - NumPy integration example - SVG rasterization example Also added examples for flowchart, sequence diagram, and class diagram generation. Update .gitignore to exclude /docs/site/ directory.
1 parent 8113ba0 commit 8e22bc8

9 files changed

Lines changed: 703 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,3 +134,4 @@ ehthumbs_vista.db
134134
.trash
135135

136136
/Cargo.lock
137+
/docs/site/

‎docs/docs/api.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# Python API
2+
3+
## `mmdr.render()`
4+
5+
```python
6+
mmdr.render(
7+
diagram: str,
8+
backend: str | None = None,
9+
**opts,
10+
) -> Diagram
11+
```
12+
13+
Render a Mermaid diagram. Returns a [`Diagram`](#diagram) object.
14+
15+
The SVG is rendered **lazily** — nothing runs until you call `.svg()`,
16+
`.png()`, `.save()`, etc. The SVG result is cached, so calling `.svg()`
17+
multiple times only renders once.
18+
19+
**Parameters:**
20+
21+
| Parameter | Type | Default | Description |
22+
|---|---|---|---|
23+
| `diagram` | `str` | — | Mermaid source text |
24+
| `backend` | `str \| None` | `None` (`"merman"`) | `"merman"` or `"mermaid-rs-renderer"` |
25+
| `theme` | `str` | `"modern"` | `"modern"` or `"classic"` — mermaid-rs-renderer only |
26+
| `node_spacing` | `float` | — | Horizontal node spacing — mermaid-rs-renderer only |
27+
| `rank_spacing` | `float` | — | Vertical rank spacing — mermaid-rs-renderer only |
28+
| `aspect_ratio` | `tuple[float, float]` | — | Preferred aspect ratio — mermaid-rs-renderer only |
29+
30+
**Example:**
31+
32+
```python
33+
import mmdr
34+
35+
d = mmdr.render("flowchart LR; A-->B-->C")
36+
d = mmdr.render("flowchart LR; A-->B-->C", backend="mermaid-rs-renderer")
37+
d = mmdr.render(
38+
"flowchart LR; A-->B-->C",
39+
backend="mermaid-rs-renderer",
40+
theme="classic",
41+
node_spacing=60.0,
42+
aspect_ratio=(16, 9),
43+
)
44+
```
45+
46+
---
47+
48+
## `Diagram`
49+
50+
The object returned by `mmdr.render()`.
51+
52+
### `.svg() → str`
53+
54+
Return the diagram as an SVG string. Cached after first call.
55+
56+
```python
57+
svg = d.svg()
58+
print(svg) # <svg xmlns="http://www.w3.org/2000/svg" ...>
59+
```
60+
61+
### `.png(width, height, background) → bytes`
62+
63+
Return the diagram as PNG bytes, rasterized via resvg.
64+
65+
```python
66+
png = d.png()
67+
png = d.png(width=1200, height=800, background="#ffffff")
68+
69+
with open("output.png", "wb") as f:
70+
f.write(png)
71+
```
72+
73+
| Parameter | Type | Default | Description |
74+
|---|---|---|---|
75+
| `width` | `float \| None` | `None` | Canvas width hint in pixels |
76+
| `height` | `float \| None` | `None` | Canvas height hint in pixels |
77+
| `background` | `str \| None` | `None` | Background fill as CSS hex, e.g. `"#ffffff"`. Transparent by default. |
78+
79+
### `.raw(width, height, background) → tuple[bytes, int, int]`
80+
81+
Return raw RGBA8888 pixel data as `(bytes, width, height)`.
82+
Stride is `width * 4`, row-major, top-to-bottom.
83+
No encoding — the pixel buffer comes straight out of resvg.
84+
85+
```python
86+
raw, w, h = d.raw(background="#ffffff")
87+
print(f"{w}×{h}, {len(raw)} bytes") # 640×480, 1228800 bytes
88+
```
89+
90+
### `.numpy(width, height, background) → np.ndarray`
91+
92+
Return an `(H, W, 4)` NumPy array, dtype `uint8`, RGBA channel order.
93+
Requires `numpy`. No Pillow needed.
94+
95+
```python
96+
arr = d.numpy()
97+
print(arr.shape) # (480, 640, 4)
98+
print(arr.dtype) # uint8
99+
100+
# Drop alpha → RGB
101+
rgb = arr[:, :, :3]
102+
103+
# Flip upside-down
104+
import numpy as np
105+
flipped = np.flipud(arr)
106+
```
107+
108+
### `.save(output, width, height, background)`
109+
110+
Save to a file. Format is inferred from the extension.
111+
112+
```python
113+
d.save("output.svg")
114+
d.save("output.png")
115+
d.save("output.png", width=1200, background="#ffffff")
116+
```
117+
118+
Supported extensions: `.svg`, `.png`.
119+
120+
### `.pdf() → bytes`
121+
122+
!!! warning "Not yet implemented"
123+
PDF export is planned for a future release.
124+
125+
---
126+
127+
## `mmdr.backends() → list[str]`
128+
129+
Return the list of backends compiled into this wheel.
130+
131+
```python
132+
mmdr.backends()
133+
# ['merman', 'mermaid-rs-renderer']
134+
```
135+
136+
---
137+
138+
## `mmdr.svg_to_png()`
139+
140+
```python
141+
mmdr.svg_to_png(
142+
svg: str,
143+
width: float | None = None,
144+
height: float | None = None,
145+
background: str | None = None,
146+
) -> bytes
147+
```
148+
149+
Convert an SVG string to PNG bytes using resvg.
150+
Useful if you already have an SVG from another source.
151+
152+
```python
153+
from mmdr import svg_to_png
154+
155+
svg = open("existing.svg").read()
156+
png = svg_to_png(svg, width=800, background="#ffffff")
157+
```
158+
159+
---
160+
161+
## `mmdr.svg_to_raw()`
162+
163+
```python
164+
mmdr.svg_to_raw(
165+
svg: str,
166+
width: float | None = None,
167+
height: float | None = None,
168+
background: str | None = None,
169+
) -> tuple[bytes, int, int]
170+
```
171+
172+
Convert an SVG string to raw RGBA8888 pixel data.
173+
Returns `(bytes, width, height)`.
174+
175+
```python
176+
from mmdr import svg_to_raw
177+
178+
raw, w, h = svg_to_raw(open("existing.svg").read())
179+
```
180+
181+
---
182+
183+
## Jupyter integration
184+
185+
`Diagram` implements `_repr_svg_()`, so it renders inline automatically
186+
in Jupyter notebooks and IPython — no extra code needed:
187+
188+
```python
189+
import mmdr
190+
191+
# evaluating this in a cell displays the diagram inline
192+
mmdr.render("sequenceDiagram\n Alice->>Bob: Hello!\n Bob-->>Alice: Hi!")
193+
```

‎docs/docs/backends.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Backends
2+
3+
mmdr ships with two Rust rendering engines. Both produce SVG from Mermaid
4+
source text. Everything else — PNG, raw pixels, NumPy — is handled by
5+
[resvg](https://github.com/RazrFalcon/resvg) regardless of which backend
6+
you choose.
7+
8+
## Comparison
9+
10+
| | `merman` | `mermaid-rs-renderer` |
11+
|---|:---:|:---:|
12+
| **Default** | ✅ | — |
13+
| **Diagram parity** | Full (Mermaid @11.15.0) | Common types only |
14+
| **Speed** | Fast | Faster |
15+
| **Layout options** | — | `theme`, `node_spacing`, `rank_spacing`, `aspect_ratio` |
16+
17+
## Diagram support
18+
19+
| Diagram type | `merman` | `mermaid-rs-renderer` |
20+
|---|:---:|:---:|
21+
| flowchart / graph | ✅ | ✅ |
22+
| sequenceDiagram | ✅ | ✅ |
23+
| classDiagram | ✅ | ✅ |
24+
| stateDiagram | ✅ | ✅ |
25+
| erDiagram | ✅ | ✅ |
26+
| pie | ✅ | ✅ |
27+
| gantt | ✅ | ✅ |
28+
| timeline | ✅ | ✅ |
29+
| mindmap | ✅ | ✅ |
30+
| gitGraph | ✅ | ✅ |
31+
| xychart | ✅ | ✅ |
32+
| block diagram | ✅ | ❌ |
33+
| architecture | ✅ | ❌ |
34+
| kanban | ✅ | ❌ |
35+
| c4diagram | ✅ | ❌ |
36+
| sankey | ✅ | ❌ |
37+
| packet | ✅ | ❌ |
38+
39+
## When to use which
40+
41+
**Use `merman` (default) when:**
42+
43+
- You need a diagram type not supported by `mermaid-rs-renderer`
44+
- Output correctness and parity with the official library matters
45+
- You don't need layout fine-tuning
46+
47+
**Use `mermaid-rs-renderer` when:**
48+
49+
- You're rendering simple flowcharts or common diagrams at high volume
50+
- You want to control layout parameters (`node_spacing`, `aspect_ratio`, etc.)
51+
- Every millisecond counts
52+
53+
## Selecting a backend
54+
55+
=== "Python"
56+
57+
```python
58+
import mmdr
59+
60+
# merman (default)
61+
d = mmdr.render("flowchart LR; A-->B")
62+
63+
# mermaid-rs-renderer
64+
d = mmdr.render(
65+
"flowchart LR; A-->B",
66+
backend="mermaid-rs-renderer",
67+
theme="classic",
68+
node_spacing=60.0,
69+
rank_spacing=80.0,
70+
aspect_ratio=(16, 9),
71+
)
72+
```
73+
74+
=== "CLI"
75+
76+
```bash
77+
# merman (default)
78+
mmdr -i diagram.mmd -o output.svg
79+
80+
# mermaid-rs-renderer
81+
mmdr -i diagram.mmd -o output.svg --backend mermaid-rs-renderer --theme classic
82+
```

‎docs/docs/cli.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# CLI Reference
2+
3+
After `pip install mmdr`, the `mmdr` command is available on your PATH.
4+
It works similarly to the official [mermaid-cli](https://github.com/mermaid-js/mermaid-cli)
5+
(`mmdc`), but starts in milliseconds — no browser to boot.
6+
7+
## Basic usage
8+
9+
```bash
10+
mmdr -i diagram.mmd -o output.svg
11+
mmdr -i diagram.mmd -o output.png
12+
```
13+
14+
The output format is inferred from the file extension. Supported: `.svg`, `.png`.
15+
16+
## Stdin / stdout
17+
18+
Use `-` to read from stdin or write to stdout:
19+
20+
```bash
21+
# stdin → stdout
22+
echo 'flowchart LR; A-->B-->C' | mmdr -i - -o -
23+
24+
# stdin → file
25+
echo 'flowchart LR; A-->B-->C' | mmdr -i - -o diagram.svg
26+
27+
# file → stdout
28+
mmdr -i diagram.mmd -o -
29+
```
30+
31+
## Options
32+
33+
| Flag | Default | Description |
34+
|---|---|---|
35+
| `-i`, `--input` | `-` (stdin) | Input `.mmd` file |
36+
| `-o`, `--output` | `-` (stdout) | Output file |
37+
| `-e`, `--format` | auto | Output format: `svg` or `png` |
38+
| `--backend` | `merman` | Rendering backend: `merman` or `mermaid-rs-renderer` |
39+
| `-w`, `--width` | — | Canvas width in pixels (PNG) |
40+
| `-H`, `--height` | — | Canvas height in pixels (PNG) |
41+
| `-b`, `--background` | transparent | Background color, e.g. `'#ffffff'` (PNG) |
42+
| `-t`, `--theme` | `modern` | Color theme: `modern` or `classic` (mermaid-rs-renderer only) |
43+
| `--node-spacing` | — | Horizontal node spacing (mermaid-rs-renderer only) |
44+
| `--rank-spacing` | — | Vertical rank spacing (mermaid-rs-renderer only) |
45+
| `--aspect-ratio` | — | Preferred aspect ratio, e.g. `16:9` (mermaid-rs-renderer only) |
46+
| `--info` | — | Render Mermaid's built-in info diagram and print its text |
47+
| `--version` | — | Print mmdr version and exit |
48+
| `-h`, `--help` | — | Show help |
49+
50+
## Examples
51+
52+
```bash
53+
# PNG with white background and fixed size
54+
mmdr -i diagram.mmd -o output.png \
55+
--width 1200 \
56+
--height 800 \
57+
--background '#ffffff'
58+
59+
# Use the faster backend
60+
mmdr -i diagram.mmd -o output.svg --backend mermaid-rs-renderer
61+
62+
# Classic Mermaid theme
63+
mmdr -i diagram.mmd -o output.svg \
64+
--backend mermaid-rs-renderer \
65+
--theme classic
66+
67+
# Batch convert all .mmd files in a directory
68+
for f in diagrams/*.mmd; do
69+
mmdr -i "$f" -o "${f%.mmd}.svg"
70+
done
71+
72+
# Also works as a Python module
73+
python -m mmdr -i diagram.mmd -o output.svg
74+
```

0 commit comments

Comments
 (0)