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

First Post!

tmbb

tmbb

Pinging @josevalim because of an old discussion (here: Access to some information not available in mix xref) regarding opening up parts of the Mix.Xref for external use. Currently, Guaxinim requires access to the runtime_dispatches and compile_dispatches to find the function calls in the source. I assume similar projects might be interested in this information too.

Making these fields accessible (properly encapsulated, of course) doesn’t seem o constrain Mix.Xref a lot.

Also, some parts of Guaxinim could be included in Mix.Xref. Currently, Mix.Xref doesn’t find intra-module function calls, which is very easy to do with access to the BEAM debug chunks.

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?

Last Post!

tmbb

tmbb

Bug fixing version released

  • The major bug has been fixed.
  • There are some improvements in CSS styles

Where Next?

Popular in Announcing Top

KronicDeth
Elixir plugin for JetBrain’s IntelliJ Platform (including Rubymine) This is a plugin that adds support for Elixir to JetBrains IntelliJ...
289 36820 110
New
danschultzer
In short Plug n’ play OAuth 2.0 provider library. Just set up a resource owner schema with Ecto (your user schema), install the dependen...
New
michalmuskala
Hello everybody. I have just released Jason - a new JSON library. You might be wondering, why do we need a new library? The primary foc...
New
wfgilman
I’ve cleaned up and open sourced three financial libraries I was using for my company. They are bindings for the APIs of these three comp...
New
mspanc
I am pleased to announce an initial release of the Membrane Framework - an Elixir-based framework with special focus on processing multim...
New
tmbb
I’ve decided to create this topic to discuss optimization possibilities for something like Phoenix LiveView. I’ve created this topic unde...
144 10847 141
New
restlessronin
The repo is at GitHub - cyberchitta/openai_ex: Community maintained Elixir library for OpenAI API · GitHub. Docs are at OpenaiEx User Gu...
152 10796 134
New

Other popular topics Top

electic
Hi, I am new to Elixir. I am trying to use the DateTime component to insert a date into MySQL however the there seems to be no way to fo...
New
New
nsuchy
Hi. I’ve noticed that Windows Powershell has it’s own IEX command and you cannot access Elixir’s IEX due to the conflict. This isn’t a cr...
New
sorentwo
Hello! tl;dr Announcing Oban, an Ecto based job processing library with a focus on reliability and historical observability. After spen...
985 44778 311
New
JorisKok
I have a server on AWS, and was running a load test using artillery. When looking at the Phoenix dashboard I see the Ports going to 100% ...
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

We're in Beta

About us Mission Statement