l3nz
Not sure if I’m the only one, but I often find myself designing Elixir projects using AsciiDoctor - because I find the embedded PlantUML drawings very useful to model graphically processes, supervision trees and messages flowing between multiple GenServers.
I think that it would be useful to have such drawings as a part of the “standard” documentation that comes with an Elixir project, as generated by ExDocs - I used to do it with a JS library that does it at runtime, but it would be just as easy to leverage a local PlantUML or a webserver, generate the SVG for once, and add it to the documentation.
So I’m starting to play around with these ideas - had a couple of free hours and was able to generate and embed them, and add two functions to my SayCheezEx to allow easy generation - if you are curios, this is what I got: SayCheezEx — say_cheez_ex v0.3.6 . It’s interesting how PlantUML has actually a huge number of drawings, and a lot of them could be useful to improve documentation.
Am I the only one toying with these ideas? How could they be made better? Is there a way to make them easier to use than just
module Foo do
import SayCheezEx, only: [uml: 1, graphviz: 1]
@moduledoc """
Here goes a Graphviz graph:
#{graphviz("digraph { Sup -> GenServ }")}
Here a PlantUML graph:
#{uml("""
Bob -> Alice : I do love UML in documentation
Alice -> Bob : me too!
""")}
"""
...
end
(those functions can be massively improved - I’d like to use a local install and if not available to fall back on a webservice - and caching is not complete yet. But it’s a start…)
Where Next?
Trending in Discussions
Other Trending Topics
Latest on Elixir Forum
Sponsor Spotlight
Deploy Phoenix to your own VPS with PaaS ease: push-to-deploy, zero downtime, auto SSL, managed Postgres. 14-day free trial at potions.io
Categories:
Sub Categories:
Forums
Popular Tags
- #ecto
- #liveview
- #troubleshooting
- #learning-elixir
- #library
- #deployment
- #erlang
- #testing
- #genserver
- #mix
- #absinthe
- #remote-other
- #otp
- #plug
- #how-to-question
- #macros
- #postgres
- #elixirconf
- #channels
- #exunit
- #discussion
- #code-sync
- #podcasts
- #javascript
- #onsite
- #dialyzer
- #docker
- #authentication
- #umbrella
- #full-time-contract
- #podcasts-by-brainlid
- #ecto-query
- #ai
- #elixirconf-us
- #blog-post
- #elixir-ls
- #phoenix_html
- #iex
- #graphql
- #genstage
- #websockets
- #supervisor
- #advent-of-code
- #distillery
- #processes
- #api
- #forms
- #hex
- #security
- #metaprogramming
Our Sponsors
Build Elixir applications with speed and confidence.
Supporting innovation across the BEAM ecosystem.
We build reliable cloud platforms for business-critical systems.
Catch errors, track performance, monitor hosts and more.
Elixir, Erlang & BEAM conferences from Code Sync - join us in 2026!
Practical resources that improve the lives of professional developers.
Bringing learning, work and compliance together since 1987.
**Building the future of software with AI, trust, and human connection.**
The team behind Membrane, Popcorn, LiveDebugger. Available for hire.
Courses that'll move you from confusion to "Aha, now I get it!"
Showing Posts 1 to 10- Show Best Posts
- Show All (oldest first)
- Show All (newest first)
kokolegorille
I have done something similar with mermaid js.
l3nz
Yes that’s what I used to do - but I like the idea of having an image generated just once, and not at runtime. And PlantUML is a powerhouse of graphs.
fuelen
The benefit of this idea is also a drawback of it. Such approach significantly increases compilation times.
l3nz
Well, yes and no, Yes - of course - when you have new or modified graphs, but the images can be cached effectively, so the difference - in practice - is unnoticeable.
hauleth
Ideally that could be done only during documentation generation. Unfortunately there is no way to have backward compatible way to extend Markdown/CommonMark that would allow to implement such thing.
l3nz
If you cache the results based on the actual graph recipe, it’s technically executed every time, but you don’t care because it does not slow you down. (Come to think of it: under which environment is documentation generated?)
hauleth
Though it is executed every time when you compile project, which puts compile-time dependency on PlantUMl being available in your system. That can be pretty painful for CI or if your project is a library.
l3nz
Actually, PlantUML is also available as a webservice, or you can even host your own, so I was thinking of trying a local version first, and going for the webservice if not installed. In the library as it is today, it uses the webservice.
hauleth
Then you have requirement on being on-line and that you can reach given website. That also make your compilation non idempotent, which also can be not desirable, especially in corporate environments, CIs, and other environments where you want to control/disallow networks during builds.
l3nz
If you need strong idempotency, you add the PlantUML binary to your local build environment, or run a local server. But my feeling is that online will be “good enough” for most of us