tmbb

tmbb

Guaxinim - Literate Programming with Hyperlinked Source

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).

Most Liked

josevalim

josevalim

Creator of Elixir

To avoid breaking changes in the future it should definitely be a list of maps. But yes, please open up an issue. We can have it as Mix.Tasks.Xref.calls/0.

josevalim

josevalim

Creator of Elixir

The issue is the API guarantees. For example, last week we changed runtime_dispatches and compile_dispatches to also include the file in some cases and that would have broken any code that relied on those functions to return only lines, as it did before. It has more information now but the change could be considered a breaking one.

The other downside of relying on runtime_dispatches and compile_dispatches is that then it is a tool specific to Mix? Could I for example have a foo.exs file that would just work with that?

tmbb

tmbb

Yes, that’s enough, but I’d prefer a normal Elixir function instead of a command that forced me to parse text. For each function, I need something like:

{{module, function, arity}, caller_module, file, line}

Or possibly a map instead of a tuple. The caller_module might be optional, I have to see if I can derive it from the line number alone.

Maybe I should file an issue asking for the minimum amount of information I can’t derive any other way?

Where Next?

Popular in Announcing Top

gabrielpoca
Hello everyone! I want to share with you something that I’m really proud of: https://stillstatic.io/ Still is a static site builder for...
New
Crowdhailer
I have been updating a library that allows you to pipe between functions that use the erlang result tuple convention. Assuming you have ...
New
maltoe
Hello! Came here to announce ChromicPDF, a pet project PDF generator I’ve been working on for the past few months. Why another PDF gener...
New
alisinabh
Hey everyone i’ve developed a library for Jalaali calendar for elixir which supports converting Gregorian dates to Jalaali and vice vers...
New
Eiji
ExApi is a library that I’m developing now and hope release soon This library will allow to: list all apis list all api implementation...
New
woutdp
Hi! I wanted to introduce my latest project LiveSvelte. It allows you to render Svelte inside LiveView with end-to-end reactivity. It’s ...
New
aditya7iyengar
Rummage.Ecto and Rummage.Phoenix provide ways to perform Searching, Sorting and Pagination over Ecto queries and Phoenix collections. Fo...
New
Jskalc
Hi! Today, after a couple weeks of development I’ve released v0.1 of LiveVue. It’s a seamless integration of Vue and Phoenix LiveView, i...
New
marcuslankenau
I feel kind of stuck with the absence of a proper xml library for Elixir. Currently I use SweetXML which was ok for me more or less to pa...
New
zoltanszogyenyi
Hey everyone :waving_hand: Excited to join this forum - I am one of the founders and current project maintainers of a popular and open-s...
New

Other popular topics Top

JakeBecker
TL;DR: I’ve just released an implementation of Microsoft’s IDE-independent Language Server Protocol for Elixir. It adds language support ...
1144 53690 245
New
Nvim
Anybody knows a comprehensive comparison of Django and Phoenix, thanks for the help. Where are they similar? Where do they differ the m...
New
senggen
Erlang/OTP 25 [erts-13.2.2] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] 15:22:35.803 [error] gen_event {lager_file_backend...
New
JeremM34
Hello, how can I check the Phoenix version ? Thanks !
New
Emily
I have VueJS GUIs with the project generated using Webpack. I have Elixir modules that will need to be used by the VueJS GUIs. I forese...
New
fireproofsocks
Forgive me if this is obvious, but how does one delete a database record WITHOUT selecting it first? Ecto.Repo — Ecto v3.14.0 has exampl...
New
gausby
I asked this very same question on twitter and got some interesting feedback, but I thought it would be a good question to ask here as we...
1207 39297 209
New
chrismccord
This release brings a number of exciting features, including integration with the new Phoenix LiveDashboard and Phoenix LiveView. There h...
New
Brian
What is the proper way to load a module from a file in to IEX? In the python world, doing something like this pretty standard: from ....
New
dogweather
I wrote this comment on r/haskell, and it’s not popular there. :wink: But I think I’m on to something… Haskell reminds me of Java, and e...
New

We're in Beta

About us Mission Statement