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).
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.
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).
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.
Heh, this is really cool, a very nice source viewer! Definitely needs that dark theme though. ^.^
Perhaps some of the vertical whitespace in lines to be reduced too?
Well, I can give you a way of passing your custom CSS file. It’s easy.
And the pages use mostly bootstrap classes for layout, so if you know bootstrap you can make it work.
It’s all HTML and CSS now. The only JS is the one required by Makeup to match delimiters on mouseover. I don’t want to include more JS (I don’t like having a little JS - I prefer either no JS ot full-blown framework).
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?
Regarding API stability, couldn’t you provide s public function that returned maps isntead of tuples? That way even if you have new information you won’t break anything, even if the user uses pattern matching.
Yes, it depends on Mix. I use Mix to read the compile manifests from which I take the data I mentioned above. I don’t know if this can be made not to depend on Mix easily. On the other hand, it can be made independent of the mix.exs file itself. I ha e to try and decouple it as much as possible
You’re asking if this works on .exs files instead of .ex? Sadly it doesn’t. But if you have a way of including those files in the compile manifests and generate BEAM files from them it can work, of course.
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:
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.
I was thinking about adding the following features.
I’d like to have a special page which shows, for each function all functions that call it. I would like to have something in which when you click a function definition you’d be taken to the corresponding page where you could see all places where the function is called. This would be very useful to get a sense of how the function fits in the whole.
For example, if you have this definitions:
def my_func(x, y), do: ...
when you clicked the my_func name you would be redirected to a page where you can find all functions and modules that call my_func. This is pretty much trivial to implement (I have a function call database that makes it easy), I just have
to make time for it.
I would like to have a function call graph or dependency graph somewhere. I can either embed a static image of the graph, but that’s not very useful. An interactive graph would be better. There are GraphViz implementations in Javascript, so this can be doable.
That would be quite awesome I’d say, it’s own page or a pop-in or so unpoly can make another page as an embedded popup as an example). ^.[1]
I would like to have a function call graph or dependency graph somewhere. I can either embed a static image of the graph, but that’s not very useful. An interactive graph would be better. There are GraphViz implementations in Javascript, so this can be doable.
[/quote]
The image like in C++'s Doxygen? That’d be very useful to see the whole generation set. I think xref can already generate those in graphviz so that side should be quite easy.
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.
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.
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.
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. ^.^
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.
