tmbb
I’ve released a tool for “inverse literate programming”. It takes a normal Elixir project and creates a website in which each page corresponds to an elixir source file and where the comments are rendered as HTML and the code is rendered with syntax highlighting. More importantly, in the code, when you click a function you are taken to it’s definition (in the current project , to the hexdocs for functions imported from Hex packages and to the Erlang docs for functions from the Erlang standard library).
Demo here: https://tmbb.github.io/guaxinim/guaxinim.ex.html. It’s Guaxinim’s own source processed with Guaxinim, probably overly-annotated; it needs refactoring badly.
Example of all kinds of hyperlinks that are supported: https://tmbb.github.io/guaxinim/guaxinim_test.ex.html
It’s very easy to use. Just add to the dependencies of your project and run mix guaxinim.render.
You might find it useful to document complex algorithms or programs with non-obvious control-flow.
Also, the hyperlinks make it very easy for programmers to explore the source.
Detailed instructions can be found in the README: GitHub - tmbb/guaxinim: Literate programming for Elixir, inspired by Docco and Pycooon · GitHub
This is probably still a little buggy (although I can’t find any bugs now). It won’t probably eat your source.
It depends on some Mix.Xref features that aren’t part of the Public API, so unless those features are stabilized, this might break in future Elixir versions. It depends on Elixir 1.5.
The goals here are quite similar to those of the Source Graph project, but read-only. The interesting part is that for many languages (like python, for example, Ruby is probably the same) Source Graph is a huge undertaking requiring a decent research effort, and Elixir has almost everything it needs either in the compiler or in the BEAM debug chunks xD
Future Developments
- Refactor the code so that it can be used independently of the Mix task
- The CSS style for the text needs some work (I’m happy with the CSS style of the code)
- It needs a “Night Mode”, like ExDoc
- Add some functionality to include Markdown files for more in-depth explanation of design features.
- Better navigation
- Add breadcrumbs (also part of “Better navigation”)
- Contribute PRs to upstream projects: Amnesia (a mnesia wrapper, appears to have some problems with missing module
requires) and Makeup (sigils without interpolation currently highlight as if they supported interpolation).
Where Next?
Trending in Announcing
Other Trending Topics
Latest on Elixir Forum
Sponsor Spotlight
Catch errors, track performance, monitor hosts and more.
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
- #elixirconf-us
- #ai
- #blog-post
- #elixir-ls
- #phoenix_html
- #iex
- #graphql
- #genstage
- #websockets
- #supervisor
- #advent-of-code
- #distillery
- #processes
- #api
- #forms
- #metaprogramming
- #hex
- #security
Our Sponsors
Build Elixir applications with speed and confidence.
Supporting innovation across the BEAM ecosystem.
Catch errors, track performance, monitor hosts and more.
Error tracking, logs, uptime, and Just Enough APM. Built for developers.
Elixir, Erlang & BEAM conferences from Code Sync - join us in 2026!
Practical resources that improve the lives of professional developers.
**Building the future of software with AI, trust, and human connection.**
The deployment platform built for Elixir: PaaS ease, VPS control.
The team behind Membrane, Popcorn, LiveDebugger. Available for hire.
Courses that'll move you from confusion to "Aha, now I get it!"
Showing Posts 23 to 14- Show Best Posts
- Show All (oldest first)
- Show All (newest first)
tmbb
Bug fixing version released
tmbb
By all means, let your family drag you somewhere xD I won’t be able to review your PR any time soon anyway
ryh
grapherl might give you some inspiration. If I remember correctly, it generates dot files that you can then render with graph viz
OvermindDL1
Adding a class takes javascript, instead you’d match on the
::checkedattribute of the checkbox followed by+'s or so everything after it. ^.^Do not have time at the moment, but poke me, hmm, maybe tomorrow and I might? I’m off work tomorrow so I may have free time (or my family will drag me out, one or the other). ^.^;
tmbb
Could you sumbit a PR to the template, please? I’m not a CSS wizard, but I can probably steal a dark theme from another python Sphinx project if you can add a class to the body element with pure CSS.
OvermindDL1
Actually it ‘technically’ doesn’t… ^.^;
It only needs javascript to ‘persist’ the changes. ^.^
If a checkbox is, say, at the top of
<body>with a label right after it (or before, or around, or whatever) then CSS can be written to choose 1 of 2 ‘branches’ basically (depending on it’s checked state) to use different sets of CSS. This is pretty trivial to do with SCSS (and I use this trick a lot) and you can make the checkbox invisible and put the label where-ever you want to. ^.^tmbb
Sure. Guaxinim’s output is independent of Javascript and I intend to keep it like that for the most part. Except for the night mode you’re asking about, that will require JS to switch a CSS class.
OvermindDL1
Make sure it at least displays something useful without javascript. ^.^
tmbb
Exactly like this. Graphviz generates great “static” images, but there are some JS libraries that generate dynamic images. I’m still not sure what I want to use.
tmbb
Important: Guaxinim has a serious bug which will probably make it not work for anything that’s not it’s own source. I won’t be able to fix it for a while.
EDIT: In my defense, my guarantee was taht it wouldn’t eat your source, not that it would work properly.