Skip to content

Fix bin/gen_diagrams that is referenced in docs #1291

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jeff-hykin merged 5 commits into from
Feb 24, 2026
Merged

Fix bin/gen_diagrams that is referenced in docs #1291

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a5cff27
add missing command
jeff-hykin Feb 18, 2026
f254a3c
Apply suggestion from @greptile-apps[bot]
jeff-hykin Feb 18, 2026
aaa4e98
fix
jeff-hykin Feb 18, 2026
028429a
Merge branch 'jeff/fix/gen-diagrams' of github.com:dimensionalOS/dimo…
jeff-hykin Feb 18, 2026
1056faa
Update bin/gen-diagrams
jeff-hykin Feb 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions bin/gen-diagrams
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
#!/usr/bin/env bash
set -euo pipefail

REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "$REPO_ROOT"

# if md-babel-py doesnt exist
if [ -z "$(command -v "md-babel-py")" ]; then
# if nix doesnt exist
if [ -z "$(command -v "nix")" ]; then
echo "Error: md-babel-py required for running gen-diagrams." >&2
echo " Either install nix or install md-babel-py" >&2
echo " https://github.com/leshy/md-babel-py" >&2
exit 1
# use nix if local command doesn't exist
else
md-babel-py() {
nix run github:leshy/md-babel-py -- "$@"
}
fi
fi

diagram_langs="asymptote,pikchr,openscad,diagon"
if [[ "$#" -gt 0 ]]; then
for arg in "$@"; do
md-babel-py run "$arg" --lang "$diagram_langs"
done
else
while IFS= read -r file; do
md-babel-py run "$file" --lang "$diagram_langs"
done < <(find ./docs -type f -name '*.md' | sort)
fi
2 changes: 1 addition & 1 deletion docs/development/writing_docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,5 @@
1. Where to put your docs:
- If it only matters to people who contribute to dimos (like this doc), put them in `docs/development`
- Otherwise put them in `docs/usage`
2. Run `bin/gen_diagrams` to generate the svg's for your diagrams. We use [pikchr](https://pikchr.org/home/doc/trunk/doc/userman.md) as a diagram language.
Copy link
Contributor

@spomichter spomichter Feb 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@leshy this is your stuff is this fine

Copy link
Contributor

@leshy leshy Feb 19, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All this does is executes md-babel-py run - this is just another adapter layer to maintain and should be a personal shell alias not a /bin/ script imo.

if others need this, that's ok and can add it - but expectation is for scripts in /bin/ to always work and be up to date

Copy link
Member Author

@jeff-hykin jeff-hykin Feb 20, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

~30 lines is not an alias; even ignoring the installation help/check, at the bottom there's a for loop for iterating over all the file paths -- a for loop doesn't fit in an alias. I have lots of my own aliases for things that are just-for-me. This was designed specifically to help others.

Idk why but md-babel-py seems to only be able to handle one file path at a time, using shell globbing doesn't work. If you add support for that it would make this wrapper less necessary.

expectation is for scripts in /bin/ to always work

Yes? This function should always work. If contributors are not able to generate diagrams for docs in one line thats a problem IMO. Why would we make each person on the team copy this wrapper and define it in their own shell?
If we add a new diagram lang we can just change this function instead of telling everyone else to change their alias's.

Copy link
Member Author

@jeff-hykin jeff-hykin Feb 20, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If anything IMO it would be nice to add a --watch flag to this script so that real-time editing of diagrams can be rendered locally instead of needing to run the command every time.

Also I made a PR on md-babel-py to make it work with Nix on MacOS whenever you get the chance to merge it:
leshy/md-babel-py#1

Copy link
Contributor

@leshy leshy Feb 21, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok I merged your md-babel PR, and published to pypy (v1.1.2) tnx for mac support!

I actually didn't write a single diagram by hand yet (have you?) agents have been drawing those for me, in docs instructions they know how to regenerate, this is why I didn't work on ergonomics of this.

but all above is good and reasonable imo, I'd prefer to add these things to md-babel-py directly, both --watch and --recursive, instead of adding an adapter layer like this. md-babel-py is a mostly quickly vibed project for me to write the docs, so I'd just vibe those commands as well.

As for re-generating diagrams, I'd add an option (temporarily) directly to md-babel-py - --diagrams but actually much better, I wouldn't differentiate code blocks vs diagram blocks and I'd add some caching mechanism (hash in code block args after language) for unchanged code blocks to not be re-evaluated.

I still think above adds a random layer that should be in md-babel-py but won't block since not very important, I let you decide

Copy link
Member Author

@jeff-hykin jeff-hykin Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

both --watch and --recursive,

I agree, would definitely prefer that to be builtin to md-babel.

For diagrams specifically I think for speed it makes sense to just want to generate diagrams (it can take quite a while to run the full code in blueprints.md), and also diagrams can't (or shouldn't) have effects outside of making an image/svg. Maybe a cache plus block-change-detection in md-babel would make it where that doesnt matter.

Once md-babel has --watch let's revisit and just have a "we use md-babel for our docs/diagrams" but for now I think bin/gen-diagrams is a useful stop-gap.

1 month from now I think it would be good to re-asses all the stuff in bin (I'm pretty sure robot debugger doesnt work, and bin/pytest-fast is an alias-level wrapper)

2. Run `bin/gen-diagrams` to generate the svg's for your diagrams. We use [mermaid](https://mermaid.js.org/intro/) (no generation needed) and [pikchr](https://pikchr.org/home/doc/trunk/doc/userman.md) as diagrams languages.
3. Use [md-babel-py](https://github.com/leshy/md-babel-py/) (`md-babel-py run thing.md`) to make sure your code examples work.
Loading