Guaxinim

Quick n' dirty literate programming for Elixir, inspired by Docco and Pyccoon

Unlike both Docco and Pyccoon (and any of the other Docco clones), Guaxinim turns your Elixir sources into hyperlinked HTML webpages, with links from each function or macro call into it's definition. You can browse Guaxinim's source rendered by Guaxinim itself here: https://tmbb.github.io/guaxinim/guaxinim.ex.html

Regarding hyperlinks, Guaxinim supports the following:

• If the function/macro was defined into your own project, the link leads to the local function definition in the same project (in the same page or in a different page)
• If the function/macro is defined in an external dependency from Hex or from the Elixir standard library, the link leads to the corresponding function head at hexdocs.pm.
• If the function is defined in the Erlang standard library, the link leads to the Erlang docs

For examples of all these kinds of links, see this dummy module from Guaxinim's own source: https://tmbb.github.io/guaxinim/guaxinim_test.ex.html

Text in comments or documentation attributes (@doc, @moduledoc, @typedoc) is treated as Markdown and rendered into HTML. Currently, documentation attributes must be heredocs (doc """\n...\n"""). Other sigils are not supported yet, even if they return strings. The process of extracting the text from the source is lexical only. The Elixir code is not executed or interpreted.

Installation

The package is available in Hex. It can be installed by adding guaxinim to your list of dependencies in mix.exs:

def deps do
  [
    {:guaxinim, "~> 0.1.0"}
  ]
end

User Manual

To use, just run the mix task in the command line:

mix guaxinim.render

This will create a directory named literate/ which will contain an entire website with the rendered sources from your project.

Previewing the Literate Source

Unlike ExDoc, for example, Guaxinim generates a hierarchy of nested files and directories, mirroring your project's actual layout on the file system. Most browsers won't show the styles correctly if you open the files directly. To preview them properly, you should start an HTTP server inside the literate/ directory.

A good option is the default HTTP server bundled with Python's standard library. To use it, run the following command inside the literate/ directory (if you're using Python 3):

python -m http.server 8000

Or the following (if you're using Python 2):

python -m SimpleHTTPServer 8000

Then, point your browser at: http://localhost:8000/ and explore the sources

TODO: Document configuration options

Differences from Other "Inverse Literate Programming" Tools

Like other "inverse literate programming" tools, Guaxinim highlights the source code of the files and allows rich texts in the form of Markdown (which is rendered into HTML).

On the other hand, Guaxinim is relatively innovative in that it can link functions in the source to their definitions. This makes it very easy to explore the source of an new project, as you can always go to the place where a function is defined. This can ony be done because Guaxinim deeply integrates with your mix project, and leverages tools like the BEAM debug chunks and the Mix.Xref module. Unlike other tools like Pyccoon, which supports multiple programming languages, Guaxinim is specialized for Elixir code. While it might highlight other programming languages in the future, providing hyperlinks in other programming languages is unlikely.

Another distinctive feature of Guaxinim is the fact that it uses the Makeup syntax highlighting tool. Makeup is a pure Elixir Syntax highlighting library, which is particularly good at highlighting Elixir (better than highlights.js, used by many such tools and Pygments, used by Python-based tools).

The Name

Guaxinim is the Portuguese word for raccoon. It was taken from the Old Tupi, spoken by the Tupi Indians in Brazil, and later adopted by the Portuguese occupiers and their foreign slaves. I also has an X in the name, which connects it to Elixir.

The logo is the stylized picture of a raccoon. The name was inspired by the Pyccoon inverse literate-programming tool (which by some reason has raccoon as it's logo).

By naming this after a Portuguese word, I'm contributing to the success of the Brazilian programming-language conspiracy, as discussed here: https://elixirforum.com/t/discussion-about-syntax-preferences-split-posts/3436/81