diagr 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- diagr-0.1.0/LICENSE +21 -0
- diagr-0.1.0/PKG-INFO +225 -0
- diagr-0.1.0/README.md +199 -0
- diagr-0.1.0/pyproject.toml +78 -0
- diagr-0.1.0/pyproject.toml.orig +55 -0
- diagr-0.1.0/src/diagr/__init__.py +13 -0
- diagr-0.1.0/src/diagr/__main__.py +3 -0
- diagr-0.1.0/src/diagr/build.py +117 -0
- diagr-0.1.0/src/diagr/cli.py +348 -0
- diagr-0.1.0/src/diagr/components.py +151 -0
- diagr-0.1.0/src/diagr/effects.py +386 -0
- diagr-0.1.0/src/diagr/fields.py +396 -0
- diagr-0.1.0/src/diagr/icons.py +249 -0
- diagr-0.1.0/src/diagr/iconsets/core/icons.yml +43 -0
- diagr-0.1.0/src/diagr/layout/__init__.py +0 -0
- diagr-0.1.0/src/diagr/layout/auto.py +557 -0
- diagr-0.1.0/src/diagr/layout/engine.py +367 -0
- diagr-0.1.0/src/diagr/layout/flow.py +227 -0
- diagr-0.1.0/src/diagr/layout/geometry.py +230 -0
- diagr-0.1.0/src/diagr/layout/metrics.py +35 -0
- diagr-0.1.0/src/diagr/layout/route.py +714 -0
- diagr-0.1.0/src/diagr/layout/text.py +25 -0
- diagr-0.1.0/src/diagr/live.py +76 -0
- diagr-0.1.0/src/diagr/markdown.py +87 -0
- diagr-0.1.0/src/diagr/migrations/__init__.py +40 -0
- diagr-0.1.0/src/diagr/model.py +261 -0
- diagr-0.1.0/src/diagr/parse.py +326 -0
- diagr-0.1.0/src/diagr/py.typed +0 -0
- diagr-0.1.0/src/diagr/render/assets/__init__.py +12 -0
- diagr-0.1.0/src/diagr/render/assets/contrast.js +22 -0
- diagr-0.1.0/src/diagr/render/assets/debug.js +8 -0
- diagr-0.1.0/src/diagr/render/assets/fold.js +12 -0
- diagr-0.1.0/src/diagr/render/assets/live.js +26 -0
- diagr-0.1.0/src/diagr/render/assets/page.css +115 -0
- diagr-0.1.0/src/diagr/render/assets/player.js +231 -0
- diagr-0.1.0/src/diagr/render/assets/theme-boot.js +12 -0
- diagr-0.1.0/src/diagr/render/assets/theme.js +6 -0
- diagr-0.1.0/src/diagr/render/assets/zoom.js +118 -0
- diagr-0.1.0/src/diagr/render/debug.py +61 -0
- diagr-0.1.0/src/diagr/render/html.py +222 -0
- diagr-0.1.0/src/diagr/render/scene.py +801 -0
- diagr-0.1.0/src/diagr/render/svg.py +154 -0
- diagr-0.1.0/src/diagr/scenario.py +269 -0
- diagr-0.1.0/src/diagr/source.py +118 -0
- diagr-0.1.0/src/diagr/starter.yml +30 -0
- diagr-0.1.0/src/diagr/syntax.py +493 -0
- diagr-0.1.0/src/diagr/theme.py +232 -0
- diagr-0.1.0/src/diagr/themes/contrast.yml +55 -0
- diagr-0.1.0/src/diagr/themes/default.yml +89 -0
- diagr-0.1.0/src/diagr/unparse.py +200 -0
- diagr-0.1.0/src/diagr/validate.py +341 -0
- diagr-0.1.0/src/diagr/views.py +118 -0
diagr-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 AnasImloul
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
diagr-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: diagr
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Declarative diagrams in YAML: static SVG in light and dark, and a self-contained interactive HTML page.
|
|
5
|
+
Keywords: diagram,svg,yaml,architecture,documentation
|
|
6
|
+
Author: AnasImloul
|
|
7
|
+
Author-email: AnasImloul <anas.imloul27@gmail.com>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
16
|
+
Classifier: Topic :: Documentation
|
|
17
|
+
Classifier: Topic :: Multimedia :: Graphics
|
|
18
|
+
Classifier: Typing :: Typed
|
|
19
|
+
Requires-Dist: pyyaml>=6.0
|
|
20
|
+
Requires-Python: >=3.12
|
|
21
|
+
Project-URL: Homepage, https://anasimloul.github.io/diagr/
|
|
22
|
+
Project-URL: Documentation, https://anasimloul.github.io/diagr/
|
|
23
|
+
Project-URL: Repository, https://github.com/AnasImloul/diagr
|
|
24
|
+
Project-URL: Issues, https://github.com/AnasImloul/diagr/issues
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
|
|
27
|
+
# diagr
|
|
28
|
+
|
|
29
|
+
Diagrams from a YAML file that you can read and also play. One file gives you a static SVG for light mode and one
|
|
30
|
+
for dark mode, for READMEs, docs and slides, and a single HTML page where the diagram plays a scenario step by step:
|
|
31
|
+
edges draw as a request moves along them, nodes turn active, done or failed, and text changes as the story goes.
|
|
32
|
+
|
|
33
|
+
<picture>
|
|
34
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/AnasImloul/diagr/main/tests/golden/order-flow-dark.svg">
|
|
35
|
+
<img alt="A web app posts an order to the API, which queues it for workers that write it to the orders database." src="https://raw.githubusercontent.com/AnasImloul/diagr/main/tests/golden/order-flow-light.svg">
|
|
36
|
+
</picture>
|
|
37
|
+
|
|
38
|
+
- **Static first.** The SVGs are laid out on a grid, automatically or with the cells you pin, with rounded
|
|
39
|
+
orthogonal edges, label pills and tinted groups. Icons are inlined and colours are baked in, so the files work
|
|
40
|
+
anywhere an image does.
|
|
41
|
+
- **Interactive on top.** The HTML page has a scenario player: run, play and pause, step forward and back, scrub,
|
|
42
|
+
change the speed. A diagram can have several scenarios, each with its own trigger button. Each frame's state is
|
|
43
|
+
worked out from the frame number, so stepping back or scrubbing shows exactly what playing would.
|
|
44
|
+
- **One HTML file.** Inline SVG, CSS and JavaScript. No CDN, no framework, nothing to load at runtime.
|
|
45
|
+
- **Checks that point at the line.** `diagr check` reports problems as `file:line:col`, suggests the id you probably
|
|
46
|
+
meant, and warns about what you would otherwise only spot in the picture, such as an edge running through a node.
|
|
47
|
+
- **Domain-neutral.** Nothing in the format assumes pipelines or a vendor. Vendor icons go in a folder next to the
|
|
48
|
+
diagram.
|
|
49
|
+
|
|
50
|
+
## Install
|
|
51
|
+
|
|
52
|
+
diagr needs Python 3.12 or later.
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
uv tool install diagr
|
|
56
|
+
# or
|
|
57
|
+
pip install diagr
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Quick start
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
diagr init my-flow.yml # writes a starter diagram, and never overwrites a file
|
|
64
|
+
diagr build my-flow.yml --svg --html -o dist # dist/my-flow-light.svg, dist/my-flow-dark.svg, dist/my-flow.html
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Open `dist/my-flow.html` and press **Place order** to play the scenario. While you edit,
|
|
68
|
+
`diagr watch my-flow.yml --html -o dist --serve` rebuilds on every save and serves the output at `http://127.0.0.1:8001/`,
|
|
69
|
+
where open pages reload and keep their place in the scenario.
|
|
70
|
+
|
|
71
|
+
The starter is a short order flow:
|
|
72
|
+
|
|
73
|
+
```yaml
|
|
74
|
+
version: 1
|
|
75
|
+
id: my-flow
|
|
76
|
+
title: Order processing
|
|
77
|
+
grid: {col: 200, row: 170}
|
|
78
|
+
|
|
79
|
+
groups:
|
|
80
|
+
front:
|
|
81
|
+
title: Frontend
|
|
82
|
+
tone: blue
|
|
83
|
+
nodes:
|
|
84
|
+
web: {at: [0, 0], icon: browser, title: Web app}
|
|
85
|
+
back:
|
|
86
|
+
title: Backend
|
|
87
|
+
sub: one region
|
|
88
|
+
tone: teal
|
|
89
|
+
nodes:
|
|
90
|
+
api: {at: [1, 0], icon: function, title: API, sub: validates}
|
|
91
|
+
queue: {at: [2, 0], icon: queue, title: Order queue}
|
|
92
|
+
db: {at: [3, 0], icon: database, title: Orders}
|
|
93
|
+
|
|
94
|
+
edges:
|
|
95
|
+
web -> api -> queue -> db: [POST /orders, enqueue, write]
|
|
96
|
+
|
|
97
|
+
scenarios:
|
|
98
|
+
order:
|
|
99
|
+
trigger: {at: web, label: Place order}
|
|
100
|
+
steps:
|
|
101
|
+
- {title: Submit, at: web, do: [flow web -> api]}
|
|
102
|
+
- {title: Queue, at: api, do: [flow api 400ms -> queue]}
|
|
103
|
+
- {title: Store, at: db, do: [flow queue -> db 300ms done]}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Groups hold nodes, each edge key can make several edges (`web -> api -> queue -> db` makes three, one label each),
|
|
107
|
+
and each step of a scenario says what happens: `flow web -> api` makes `web` active, draws its edge to `api`, then
|
|
108
|
+
marks `web` done.
|
|
109
|
+
|
|
110
|
+
To show a diagram in a README, use both SVGs so the image follows the reader's theme:
|
|
111
|
+
|
|
112
|
+
```html
|
|
113
|
+
<picture>
|
|
114
|
+
<source media="(prefers-color-scheme: dark)" srcset="my-flow-dark.svg">
|
|
115
|
+
<img alt="Order processing" src="my-flow-light.svg">
|
|
116
|
+
</picture>
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## What a diagram can hold
|
|
120
|
+
|
|
121
|
+
- **Groups and nodes**, nested as deep as you like, with titles, sub lines, icons, tooltips, progress cells and
|
|
122
|
+
stacked copies. Pin any of them to grid cells, or leave out `at` and diagr places them for you.
|
|
123
|
+
- **Edges**, written as chains (`a -> b -> c`), fans (`(a b) -> c`), dashed links (`a --> b`) and pairs that run
|
|
124
|
+
both ways (`a <-> b`), with labels, ports and routes of your own when you want them.
|
|
125
|
+
- **Rows and columns** that arrange a box's contents like CSS flexbox, as an alternative to grid cells.
|
|
126
|
+
- **Components**: a block of groups, nodes and edges defined once and used as named instances, with text
|
|
127
|
+
parameters.
|
|
128
|
+
- **Scenarios**: steps whose effects activate, finish or fail nodes, draw edges, fill cells, change text, show and
|
|
129
|
+
hide parts, and run side by side or on repeat.
|
|
130
|
+
- **Views**: parts of one diagram built as their own images and page, including dynamic views that number a
|
|
131
|
+
scenario's edges by step.
|
|
132
|
+
- **Themes and icons**: a default and a high-contrast theme, brand themes that change only what they need, 40 core
|
|
133
|
+
icons, and folders of your own.
|
|
134
|
+
|
|
135
|
+
## Documentation
|
|
136
|
+
|
|
137
|
+
- [Diagram format](https://anasimloul.github.io/diagr/format/): everything a diagram file can say, with examples
|
|
138
|
+
- [Themes and icons](https://anasimloul.github.io/diagr/themes-and-icons/)
|
|
139
|
+
- [Docs and CI](https://anasimloul.github.io/diagr/integrations/): ```` ```diagr ```` blocks in MkDocs, and a GitHub Actions workflow that keeps
|
|
140
|
+
committed SVGs in step with their diagrams
|
|
141
|
+
- [How diagr compares](https://anasimloul.github.io/diagr/comparison/) with D2, Mermaid, Structurizr, LikeC4, Ilograph and IcePanel, and when
|
|
142
|
+
another tool fits better
|
|
143
|
+
- [Examples](https://anasimloul.github.io/diagr/examples/), with their source in [`examples/`](https://github.com/AnasImloul/diagr/tree/main/examples):
|
|
144
|
+
- `order-flow`: the example above, looping, with a dead-letter queue
|
|
145
|
+
- `cloud-architecture`: pull-based workers, retries, and a captions path running alongside the job
|
|
146
|
+
- `multi-region`: nested groups, a component used twice and three scenarios
|
|
147
|
+
- `data-platform`: a three-instance component, three levels of nesting, a merge junction and four scenarios
|
|
148
|
+
- `event-driven`: no positions at all, so every node is placed automatically
|
|
149
|
+
|
|
150
|
+
## CLI
|
|
151
|
+
|
|
152
|
+
| Command | What it does |
|
|
153
|
+
|---|---|
|
|
154
|
+
| `diagr init [FILE] [--id ID]` | Write a starter diagram (default `diagram.yml`); never overwrites |
|
|
155
|
+
| `diagr build FILE... [--light] [--dark] [--svg] [--html] [-o DIR] [--theme T] [--debug] [--transparent]` | Write the files you ask for, at least one, for each diagram and each of its views: `--light` and `--dark` the static SVGs, `--svg` both, `--html` the page with the player; `--debug` adds the grid and route overlay to the page (G toggles it); `--transparent` leaves the background out of the SVGs |
|
|
156
|
+
| `diagr watch FILE... [--light] [--dark] [--svg] [--html] [-o DIR] [--theme T] [--interval S] [--debug] [--transparent] [--serve] [--port P]` | Rebuild the files you ask for, as `build` does, when the diagram, its icon folders or its theme file change; `--serve` also serves the output, and open pages reload on each rebuild |
|
|
157
|
+
| `diagr check FILE... [--theme T] [--strict] [--format json]` | Validate; problems are printed as `file:line:col`, or as JSON on stdout; `--strict` fails on warnings too |
|
|
158
|
+
| `diagr expand FILE [-o OUT]` | Print the diagram with its components written out as plain groups, nodes and edges and every position pinned; the output builds to the same files |
|
|
159
|
+
| `diagr icons [FILE]` | List the core icons, plus the icon folders of `FILE` if given |
|
|
160
|
+
| `diagr schema [-o FILE]` | Print the JSON Schema |
|
|
161
|
+
| `diagr --version` | Print the installed version |
|
|
162
|
+
|
|
163
|
+
`--theme` on the command line is resolved against the current folder; `theme:` in a diagram against the diagram's
|
|
164
|
+
folder.
|
|
165
|
+
|
|
166
|
+
For autocomplete in editors that support it, put `# yaml-language-server: $schema=<path>/diagr.schema.json` at the
|
|
167
|
+
top of a diagram, pointing at [`schema/diagr.schema.json`](https://github.com/AnasImloul/diagr/blob/main/schema/diagr.schema.json) or at the file
|
|
168
|
+
`diagr schema -o` writes.
|
|
169
|
+
|
|
170
|
+
## Player keys
|
|
171
|
+
|
|
172
|
+
The keys work once the diagram or the player has focus: click the diagram, or Tab to it. The rest of the page keeps
|
|
173
|
+
its keys, so Space and the arrows still scroll it.
|
|
174
|
+
|
|
175
|
+
| Key | Does |
|
|
176
|
+
|---|---|
|
|
177
|
+
| Space | Play or pause |
|
|
178
|
+
| Left, Right | Previous or next step; with Shift, one frame |
|
|
179
|
+
| Home, End | Back to the start, or to the end |
|
|
180
|
+
| `+`, `-`, `0` | Zoom in, zoom out, fit the whole diagram |
|
|
181
|
+
| `F` | Full screen |
|
|
182
|
+
| `C` | High contrast, remembered like the light or dark choice |
|
|
183
|
+
|
|
184
|
+
Ctrl or ⌘ with the scroll wheel, or a pinch, zooms around the pointer, and you can drag to pan once zoomed in.
|
|
185
|
+
Clicking a step in the list jumps to it, and with several scenarios the buttons above the progress bar switch between
|
|
186
|
+
them. A scenario with `loop: true` plays on its own and replays until you pause it.
|
|
187
|
+
|
|
188
|
+
## Development
|
|
189
|
+
|
|
190
|
+
```sh
|
|
191
|
+
uv sync
|
|
192
|
+
uv run ruff check .
|
|
193
|
+
uv run ruff format --check . # or: uv run ruff format .
|
|
194
|
+
uv run pyright
|
|
195
|
+
uv run python -m unittest discover -s tests -t .
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
`tests/golden/` holds the expected output of every example. After a change that is meant to alter the output, run
|
|
199
|
+
`DIAGR_UPDATE_GOLDEN=1 uv run python -m unittest tests.test_examples` and review the diff. After changing the format,
|
|
200
|
+
regenerate the schema with `uv run diagr schema -o schema/diagr.schema.json`; a test fails if it is out of date. One
|
|
201
|
+
test runs the player's state code with Node and is skipped when `node` is not installed.
|
|
202
|
+
`.github/workflows/ci.yml` runs all of this on every push and pull request.
|
|
203
|
+
|
|
204
|
+
The docs site is built with MkDocs Material, with the examples built from `examples/` each time:
|
|
205
|
+
|
|
206
|
+
```sh
|
|
207
|
+
uv sync --group docs
|
|
208
|
+
uv run mkdocs serve # live preview
|
|
209
|
+
uv run mkdocs build --strict # writes site/
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
`.github/workflows/docs.yml` builds it on every push to `main`, and deploys it to GitHub Pages once the repository is
|
|
213
|
+
public.
|
|
214
|
+
|
|
215
|
+
| Path | What |
|
|
216
|
+
|---|---|
|
|
217
|
+
| `src/diagr/` | The package: parser, validator, layout, scenario compiler, renderers, themes, core icons |
|
|
218
|
+
| `examples/` | Example diagrams |
|
|
219
|
+
| `schema/` | Generated JSON Schema |
|
|
220
|
+
| `tests/` | Unit tests and golden files for the examples |
|
|
221
|
+
| `tools/measure_text.py` | Regenerates the text width table from installed fonts (needs Chrome) |
|
|
222
|
+
|
|
223
|
+
## License
|
|
224
|
+
|
|
225
|
+
MIT, see [LICENSE](https://github.com/AnasImloul/diagr/blob/main/LICENSE).
|
diagr-0.1.0/README.md
ADDED
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
# diagr
|
|
2
|
+
|
|
3
|
+
Diagrams from a YAML file that you can read and also play. One file gives you a static SVG for light mode and one
|
|
4
|
+
for dark mode, for READMEs, docs and slides, and a single HTML page where the diagram plays a scenario step by step:
|
|
5
|
+
edges draw as a request moves along them, nodes turn active, done or failed, and text changes as the story goes.
|
|
6
|
+
|
|
7
|
+
<picture>
|
|
8
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/AnasImloul/diagr/main/tests/golden/order-flow-dark.svg">
|
|
9
|
+
<img alt="A web app posts an order to the API, which queues it for workers that write it to the orders database." src="https://raw.githubusercontent.com/AnasImloul/diagr/main/tests/golden/order-flow-light.svg">
|
|
10
|
+
</picture>
|
|
11
|
+
|
|
12
|
+
- **Static first.** The SVGs are laid out on a grid, automatically or with the cells you pin, with rounded
|
|
13
|
+
orthogonal edges, label pills and tinted groups. Icons are inlined and colours are baked in, so the files work
|
|
14
|
+
anywhere an image does.
|
|
15
|
+
- **Interactive on top.** The HTML page has a scenario player: run, play and pause, step forward and back, scrub,
|
|
16
|
+
change the speed. A diagram can have several scenarios, each with its own trigger button. Each frame's state is
|
|
17
|
+
worked out from the frame number, so stepping back or scrubbing shows exactly what playing would.
|
|
18
|
+
- **One HTML file.** Inline SVG, CSS and JavaScript. No CDN, no framework, nothing to load at runtime.
|
|
19
|
+
- **Checks that point at the line.** `diagr check` reports problems as `file:line:col`, suggests the id you probably
|
|
20
|
+
meant, and warns about what you would otherwise only spot in the picture, such as an edge running through a node.
|
|
21
|
+
- **Domain-neutral.** Nothing in the format assumes pipelines or a vendor. Vendor icons go in a folder next to the
|
|
22
|
+
diagram.
|
|
23
|
+
|
|
24
|
+
## Install
|
|
25
|
+
|
|
26
|
+
diagr needs Python 3.12 or later.
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
uv tool install diagr
|
|
30
|
+
# or
|
|
31
|
+
pip install diagr
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Quick start
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
diagr init my-flow.yml # writes a starter diagram, and never overwrites a file
|
|
38
|
+
diagr build my-flow.yml --svg --html -o dist # dist/my-flow-light.svg, dist/my-flow-dark.svg, dist/my-flow.html
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Open `dist/my-flow.html` and press **Place order** to play the scenario. While you edit,
|
|
42
|
+
`diagr watch my-flow.yml --html -o dist --serve` rebuilds on every save and serves the output at `http://127.0.0.1:8001/`,
|
|
43
|
+
where open pages reload and keep their place in the scenario.
|
|
44
|
+
|
|
45
|
+
The starter is a short order flow:
|
|
46
|
+
|
|
47
|
+
```yaml
|
|
48
|
+
version: 1
|
|
49
|
+
id: my-flow
|
|
50
|
+
title: Order processing
|
|
51
|
+
grid: {col: 200, row: 170}
|
|
52
|
+
|
|
53
|
+
groups:
|
|
54
|
+
front:
|
|
55
|
+
title: Frontend
|
|
56
|
+
tone: blue
|
|
57
|
+
nodes:
|
|
58
|
+
web: {at: [0, 0], icon: browser, title: Web app}
|
|
59
|
+
back:
|
|
60
|
+
title: Backend
|
|
61
|
+
sub: one region
|
|
62
|
+
tone: teal
|
|
63
|
+
nodes:
|
|
64
|
+
api: {at: [1, 0], icon: function, title: API, sub: validates}
|
|
65
|
+
queue: {at: [2, 0], icon: queue, title: Order queue}
|
|
66
|
+
db: {at: [3, 0], icon: database, title: Orders}
|
|
67
|
+
|
|
68
|
+
edges:
|
|
69
|
+
web -> api -> queue -> db: [POST /orders, enqueue, write]
|
|
70
|
+
|
|
71
|
+
scenarios:
|
|
72
|
+
order:
|
|
73
|
+
trigger: {at: web, label: Place order}
|
|
74
|
+
steps:
|
|
75
|
+
- {title: Submit, at: web, do: [flow web -> api]}
|
|
76
|
+
- {title: Queue, at: api, do: [flow api 400ms -> queue]}
|
|
77
|
+
- {title: Store, at: db, do: [flow queue -> db 300ms done]}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Groups hold nodes, each edge key can make several edges (`web -> api -> queue -> db` makes three, one label each),
|
|
81
|
+
and each step of a scenario says what happens: `flow web -> api` makes `web` active, draws its edge to `api`, then
|
|
82
|
+
marks `web` done.
|
|
83
|
+
|
|
84
|
+
To show a diagram in a README, use both SVGs so the image follows the reader's theme:
|
|
85
|
+
|
|
86
|
+
```html
|
|
87
|
+
<picture>
|
|
88
|
+
<source media="(prefers-color-scheme: dark)" srcset="my-flow-dark.svg">
|
|
89
|
+
<img alt="Order processing" src="my-flow-light.svg">
|
|
90
|
+
</picture>
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## What a diagram can hold
|
|
94
|
+
|
|
95
|
+
- **Groups and nodes**, nested as deep as you like, with titles, sub lines, icons, tooltips, progress cells and
|
|
96
|
+
stacked copies. Pin any of them to grid cells, or leave out `at` and diagr places them for you.
|
|
97
|
+
- **Edges**, written as chains (`a -> b -> c`), fans (`(a b) -> c`), dashed links (`a --> b`) and pairs that run
|
|
98
|
+
both ways (`a <-> b`), with labels, ports and routes of your own when you want them.
|
|
99
|
+
- **Rows and columns** that arrange a box's contents like CSS flexbox, as an alternative to grid cells.
|
|
100
|
+
- **Components**: a block of groups, nodes and edges defined once and used as named instances, with text
|
|
101
|
+
parameters.
|
|
102
|
+
- **Scenarios**: steps whose effects activate, finish or fail nodes, draw edges, fill cells, change text, show and
|
|
103
|
+
hide parts, and run side by side or on repeat.
|
|
104
|
+
- **Views**: parts of one diagram built as their own images and page, including dynamic views that number a
|
|
105
|
+
scenario's edges by step.
|
|
106
|
+
- **Themes and icons**: a default and a high-contrast theme, brand themes that change only what they need, 40 core
|
|
107
|
+
icons, and folders of your own.
|
|
108
|
+
|
|
109
|
+
## Documentation
|
|
110
|
+
|
|
111
|
+
- [Diagram format](https://anasimloul.github.io/diagr/format/): everything a diagram file can say, with examples
|
|
112
|
+
- [Themes and icons](https://anasimloul.github.io/diagr/themes-and-icons/)
|
|
113
|
+
- [Docs and CI](https://anasimloul.github.io/diagr/integrations/): ```` ```diagr ```` blocks in MkDocs, and a GitHub Actions workflow that keeps
|
|
114
|
+
committed SVGs in step with their diagrams
|
|
115
|
+
- [How diagr compares](https://anasimloul.github.io/diagr/comparison/) with D2, Mermaid, Structurizr, LikeC4, Ilograph and IcePanel, and when
|
|
116
|
+
another tool fits better
|
|
117
|
+
- [Examples](https://anasimloul.github.io/diagr/examples/), with their source in [`examples/`](https://github.com/AnasImloul/diagr/tree/main/examples):
|
|
118
|
+
- `order-flow`: the example above, looping, with a dead-letter queue
|
|
119
|
+
- `cloud-architecture`: pull-based workers, retries, and a captions path running alongside the job
|
|
120
|
+
- `multi-region`: nested groups, a component used twice and three scenarios
|
|
121
|
+
- `data-platform`: a three-instance component, three levels of nesting, a merge junction and four scenarios
|
|
122
|
+
- `event-driven`: no positions at all, so every node is placed automatically
|
|
123
|
+
|
|
124
|
+
## CLI
|
|
125
|
+
|
|
126
|
+
| Command | What it does |
|
|
127
|
+
|---|---|
|
|
128
|
+
| `diagr init [FILE] [--id ID]` | Write a starter diagram (default `diagram.yml`); never overwrites |
|
|
129
|
+
| `diagr build FILE... [--light] [--dark] [--svg] [--html] [-o DIR] [--theme T] [--debug] [--transparent]` | Write the files you ask for, at least one, for each diagram and each of its views: `--light` and `--dark` the static SVGs, `--svg` both, `--html` the page with the player; `--debug` adds the grid and route overlay to the page (G toggles it); `--transparent` leaves the background out of the SVGs |
|
|
130
|
+
| `diagr watch FILE... [--light] [--dark] [--svg] [--html] [-o DIR] [--theme T] [--interval S] [--debug] [--transparent] [--serve] [--port P]` | Rebuild the files you ask for, as `build` does, when the diagram, its icon folders or its theme file change; `--serve` also serves the output, and open pages reload on each rebuild |
|
|
131
|
+
| `diagr check FILE... [--theme T] [--strict] [--format json]` | Validate; problems are printed as `file:line:col`, or as JSON on stdout; `--strict` fails on warnings too |
|
|
132
|
+
| `diagr expand FILE [-o OUT]` | Print the diagram with its components written out as plain groups, nodes and edges and every position pinned; the output builds to the same files |
|
|
133
|
+
| `diagr icons [FILE]` | List the core icons, plus the icon folders of `FILE` if given |
|
|
134
|
+
| `diagr schema [-o FILE]` | Print the JSON Schema |
|
|
135
|
+
| `diagr --version` | Print the installed version |
|
|
136
|
+
|
|
137
|
+
`--theme` on the command line is resolved against the current folder; `theme:` in a diagram against the diagram's
|
|
138
|
+
folder.
|
|
139
|
+
|
|
140
|
+
For autocomplete in editors that support it, put `# yaml-language-server: $schema=<path>/diagr.schema.json` at the
|
|
141
|
+
top of a diagram, pointing at [`schema/diagr.schema.json`](https://github.com/AnasImloul/diagr/blob/main/schema/diagr.schema.json) or at the file
|
|
142
|
+
`diagr schema -o` writes.
|
|
143
|
+
|
|
144
|
+
## Player keys
|
|
145
|
+
|
|
146
|
+
The keys work once the diagram or the player has focus: click the diagram, or Tab to it. The rest of the page keeps
|
|
147
|
+
its keys, so Space and the arrows still scroll it.
|
|
148
|
+
|
|
149
|
+
| Key | Does |
|
|
150
|
+
|---|---|
|
|
151
|
+
| Space | Play or pause |
|
|
152
|
+
| Left, Right | Previous or next step; with Shift, one frame |
|
|
153
|
+
| Home, End | Back to the start, or to the end |
|
|
154
|
+
| `+`, `-`, `0` | Zoom in, zoom out, fit the whole diagram |
|
|
155
|
+
| `F` | Full screen |
|
|
156
|
+
| `C` | High contrast, remembered like the light or dark choice |
|
|
157
|
+
|
|
158
|
+
Ctrl or ⌘ with the scroll wheel, or a pinch, zooms around the pointer, and you can drag to pan once zoomed in.
|
|
159
|
+
Clicking a step in the list jumps to it, and with several scenarios the buttons above the progress bar switch between
|
|
160
|
+
them. A scenario with `loop: true` plays on its own and replays until you pause it.
|
|
161
|
+
|
|
162
|
+
## Development
|
|
163
|
+
|
|
164
|
+
```sh
|
|
165
|
+
uv sync
|
|
166
|
+
uv run ruff check .
|
|
167
|
+
uv run ruff format --check . # or: uv run ruff format .
|
|
168
|
+
uv run pyright
|
|
169
|
+
uv run python -m unittest discover -s tests -t .
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
`tests/golden/` holds the expected output of every example. After a change that is meant to alter the output, run
|
|
173
|
+
`DIAGR_UPDATE_GOLDEN=1 uv run python -m unittest tests.test_examples` and review the diff. After changing the format,
|
|
174
|
+
regenerate the schema with `uv run diagr schema -o schema/diagr.schema.json`; a test fails if it is out of date. One
|
|
175
|
+
test runs the player's state code with Node and is skipped when `node` is not installed.
|
|
176
|
+
`.github/workflows/ci.yml` runs all of this on every push and pull request.
|
|
177
|
+
|
|
178
|
+
The docs site is built with MkDocs Material, with the examples built from `examples/` each time:
|
|
179
|
+
|
|
180
|
+
```sh
|
|
181
|
+
uv sync --group docs
|
|
182
|
+
uv run mkdocs serve # live preview
|
|
183
|
+
uv run mkdocs build --strict # writes site/
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
`.github/workflows/docs.yml` builds it on every push to `main`, and deploys it to GitHub Pages once the repository is
|
|
187
|
+
public.
|
|
188
|
+
|
|
189
|
+
| Path | What |
|
|
190
|
+
|---|---|
|
|
191
|
+
| `src/diagr/` | The package: parser, validator, layout, scenario compiler, renderers, themes, core icons |
|
|
192
|
+
| `examples/` | Example diagrams |
|
|
193
|
+
| `schema/` | Generated JSON Schema |
|
|
194
|
+
| `tests/` | Unit tests and golden files for the examples |
|
|
195
|
+
| `tools/measure_text.py` | Regenerates the text width table from installed fonts (needs Chrome) |
|
|
196
|
+
|
|
197
|
+
## License
|
|
198
|
+
|
|
199
|
+
MIT, see [LICENSE](https://github.com/AnasImloul/diagr/blob/main/LICENSE).
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "diagr"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Declarative diagrams in YAML: static SVG in light and dark, and a self-contained interactive HTML page."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
license-files = ["LICENSE"]
|
|
8
|
+
requires-python = ">=3.12"
|
|
9
|
+
dependencies = ["pyyaml>=6.0"]
|
|
10
|
+
keywords = [
|
|
11
|
+
"diagram",
|
|
12
|
+
"svg",
|
|
13
|
+
"yaml",
|
|
14
|
+
"architecture",
|
|
15
|
+
"documentation",
|
|
16
|
+
]
|
|
17
|
+
classifiers = [
|
|
18
|
+
"Development Status :: 3 - Alpha",
|
|
19
|
+
"Environment :: Console",
|
|
20
|
+
"Programming Language :: Python :: 3",
|
|
21
|
+
"Programming Language :: Python :: 3.12",
|
|
22
|
+
"Programming Language :: Python :: 3.13",
|
|
23
|
+
"Programming Language :: Python :: 3.14",
|
|
24
|
+
"Topic :: Documentation",
|
|
25
|
+
"Topic :: Multimedia :: Graphics",
|
|
26
|
+
"Typing :: Typed",
|
|
27
|
+
]
|
|
28
|
+
|
|
29
|
+
[[project.authors]]
|
|
30
|
+
name = "AnasImloul"
|
|
31
|
+
email = "anas.imloul27@gmail.com"
|
|
32
|
+
|
|
33
|
+
[project.urls]
|
|
34
|
+
Homepage = "https://anasimloul.github.io/diagr/"
|
|
35
|
+
Documentation = "https://anasimloul.github.io/diagr/"
|
|
36
|
+
Repository = "https://github.com/AnasImloul/diagr"
|
|
37
|
+
Issues = "https://github.com/AnasImloul/diagr/issues"
|
|
38
|
+
|
|
39
|
+
[project.scripts]
|
|
40
|
+
diagr = "diagr.cli:main"
|
|
41
|
+
|
|
42
|
+
[dependency-groups]
|
|
43
|
+
dev = [
|
|
44
|
+
"ruff",
|
|
45
|
+
"pyright",
|
|
46
|
+
]
|
|
47
|
+
docs = ["mkdocs-material"]
|
|
48
|
+
|
|
49
|
+
[build-system]
|
|
50
|
+
requires = ["uv_build>=0.12,<0.13"]
|
|
51
|
+
build-backend = "uv_build"
|
|
52
|
+
|
|
53
|
+
[tool.ruff]
|
|
54
|
+
line-length = 120
|
|
55
|
+
target-version = "py312"
|
|
56
|
+
|
|
57
|
+
[tool.ruff.format]
|
|
58
|
+
exclude = ["src/diagr/layout/metrics.py"]
|
|
59
|
+
|
|
60
|
+
[tool.ruff.lint]
|
|
61
|
+
select = [
|
|
62
|
+
"E",
|
|
63
|
+
"F",
|
|
64
|
+
"W",
|
|
65
|
+
"I",
|
|
66
|
+
"B",
|
|
67
|
+
"UP",
|
|
68
|
+
]
|
|
69
|
+
|
|
70
|
+
[tool.pyright]
|
|
71
|
+
include = [
|
|
72
|
+
"src",
|
|
73
|
+
"tools",
|
|
74
|
+
"tests",
|
|
75
|
+
]
|
|
76
|
+
pythonVersion = "3.12"
|
|
77
|
+
venvPath = "."
|
|
78
|
+
venv = ".venv"
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "diagr"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Declarative diagrams in YAML: static SVG in light and dark, and a self-contained interactive HTML page."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
license-files = ["LICENSE"]
|
|
8
|
+
authors = [{ name = "AnasImloul", email = "anas.imloul27@gmail.com" }]
|
|
9
|
+
requires-python = ">=3.12"
|
|
10
|
+
dependencies = ["pyyaml>=6.0"]
|
|
11
|
+
keywords = ["diagram", "svg", "yaml", "architecture", "documentation"]
|
|
12
|
+
classifiers = [
|
|
13
|
+
"Development Status :: 3 - Alpha",
|
|
14
|
+
"Environment :: Console",
|
|
15
|
+
"Programming Language :: Python :: 3",
|
|
16
|
+
"Programming Language :: Python :: 3.12",
|
|
17
|
+
"Programming Language :: Python :: 3.13",
|
|
18
|
+
"Programming Language :: Python :: 3.14",
|
|
19
|
+
"Topic :: Documentation",
|
|
20
|
+
"Topic :: Multimedia :: Graphics",
|
|
21
|
+
"Typing :: Typed",
|
|
22
|
+
]
|
|
23
|
+
|
|
24
|
+
[project.urls]
|
|
25
|
+
Homepage = "https://anasimloul.github.io/diagr/"
|
|
26
|
+
Documentation = "https://anasimloul.github.io/diagr/"
|
|
27
|
+
Repository = "https://github.com/AnasImloul/diagr"
|
|
28
|
+
Issues = "https://github.com/AnasImloul/diagr/issues"
|
|
29
|
+
|
|
30
|
+
[project.scripts]
|
|
31
|
+
diagr = "diagr.cli:main"
|
|
32
|
+
|
|
33
|
+
[dependency-groups]
|
|
34
|
+
dev = ["ruff", "pyright"]
|
|
35
|
+
docs = ["mkdocs-material"]
|
|
36
|
+
|
|
37
|
+
[build-system]
|
|
38
|
+
requires = ["uv_build>=0.12,<0.13"]
|
|
39
|
+
build-backend = "uv_build"
|
|
40
|
+
|
|
41
|
+
[tool.ruff]
|
|
42
|
+
line-length = 120
|
|
43
|
+
target-version = "py312"
|
|
44
|
+
|
|
45
|
+
[tool.ruff.format]
|
|
46
|
+
exclude = ["src/diagr/layout/metrics.py"]
|
|
47
|
+
|
|
48
|
+
[tool.ruff.lint]
|
|
49
|
+
select = ["E", "F", "W", "I", "B", "UP"]
|
|
50
|
+
|
|
51
|
+
[tool.pyright]
|
|
52
|
+
include = ["src", "tools", "tests"]
|
|
53
|
+
pythonVersion = "3.12"
|
|
54
|
+
venvPath = "."
|
|
55
|
+
venv = ".venv"
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
2
|
+
|
|
3
|
+
from .build import Prepared, build_files, prepare
|
|
4
|
+
from .model import Diagram
|
|
5
|
+
from .parse import load_file
|
|
6
|
+
from .source import DiagramError, Problem
|
|
7
|
+
from .syntax import json_schema
|
|
8
|
+
|
|
9
|
+
__all__ = ["Diagram", "DiagramError", "Prepared", "Problem", "build_files", "json_schema", "load_file", "prepare"]
|
|
10
|
+
try:
|
|
11
|
+
__version__ = version("diagr")
|
|
12
|
+
except PackageNotFoundError:
|
|
13
|
+
__version__ = "0+unknown"
|