ExDash: Internal Elixir docs integrated with Dash

At Urbint, we pride ourselves on maintaining smooth software development tools. A crucial part of those tools is instant access to documentation via search.

This post takes a quick look at the tools we use to accomplish this, for both internal and external documentation, with Dash, Alfred, and a new Elixir package called ExDash.

A deadly doc-tooling combo

Dash is a tool for managing and searching offline documentation. It has integrations with package managers like Hex and GoDoc, making it easy to add whatever packages you use to your local machine, and it automatically keeps your docs up-to-date when those packages themselves are updated.

Offline docs are great for fast-search (no waiting for a browser to load) and if you’re working offline (say, on a plane).

The productivity tool Alfred makes it easy to write and install custom ‘workflows’ for automating common tasks. Things like caniuse and adding Trello cards take a few steps out of tasks that would otherwise risk larger interruptions and context-switches.

Alfred comes with a built in Dash integration, which makes searching for your docs as easy as [Cmd] + [Space] + ex String.repl...

Alfred’s hovering omni-bar.

Dash displaying the documentation found directly in Elixir’s source. Note the full function list on the lower left, great for scanning a module’s full surface area.

For languages that treat documentation as a first-class citizen,
easily exploring new packages is a significant productivity boost.

Note: both Alfred and Dash have free and paid versions: I recommend paying for both. Invest in your tools!

But I also have this internal code-base…

All of this documentation for source files and external packages is great,
but what if you want to be able to read and search your own docs?

Enter ExDash, an elixir package for building and syncing your local app’s Dash documentation with the Dash docs you’re already consuming.

mix docs.dash --open --name fooCodeBase

Through Dash, you can set custom prefixes to search through only specific packages. I recommend combining all of your Elixir code under the same prefix, which can help your teammates discover that you already solved that snakecase problem.

A generic search for "ex blah" now finds our internal extension to Elixir’s String module.

Our internal documentation, now visible in Dash.

A Sip of Elixir

One of Elixir’s fun features is ExUnit’s doctests, which let you write usage examples that get run as actual tests in your test suite.

The @doc strings are written in markdown. Example use-cases can be included; a line prefixed with iex> will be evaluated and asserted against the value immediately following it.

@doc """
Dedupes the spaces within `input`.
## Examples
    iex> String.Extra.dedupe_spaces(“Hello    world    “)
    “Hello world”
"""
@spec dedupe_spaces(String.t) :: String.t
def dedupe_spaces(input) do
  input
  |> String.replace(~r/\s{2,}/, “ “)
  |> String.trim()
end

This helps prevent documentation from getting stale, while providing a clear example of how to use the function itself. Pretty fancy-schmancy, huh?

Happy Documentation Dog-fooding!

ExDash can be found on github and installed via hex.

Urbint is a building Urban Intelligence with Elixir, Rust, and Elm. Check out some of our other posts here.