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