Elixir approach to documentation is awesome. Using a syntax similar to Python docstrings you can directly document your modules, functions and types in Markdown. As the documentation puts it: documentation [is] a first-class citizen.

Following this best practice (well, documenting code is more of a requirement than a best practice, even Elixir linters yell at you when you forget a @moduledoc), I documented my code. I didn’t bother thinking about how it would look once compiled using ExDoc, I only started caring about it once I was ready to publish my package to hex.pm and mix suggested to automagically upload the documentation somewhere using mix hex.docs.

My package was minimally documented, the doc was telling what was going on but my intent, the explanation about what the package was doing, intended for, how to install and use it was not in the code documentation, it was in the README.md.

How to include a readme in ExDoc / mix hex.docs

In your package’s mix.exs, in the project function, you can configure extra documentation files this way:

  def project do
    [app: :yourapp,
     version: "0.5.3",
     …
     docs: [
       main: "readme", # documentation entry point is the readme
       extras: ["README.md"] # your extra files paths, including the said readme
     ],
     …]
  end

This is nice and documented in ExDoc’s readme, but…

How to show the module version in Elixir documentation

Here’s a cool trick1 @ericmj showed me using a module attribute:

defmodule Mymodule.Mixfile do
  use Mix.Project

  @version "0.5.3"

  def project do
    [app: :mymodule,
     version: @version,
     …
     docs: [
       source_ref: "v#{@version}",
       main: "readme",
       extras: ["README.md"]
     ],
     …]
  end

And now the documentation defaults to showing the readme, includes the module version and looks awesome: https://hexdocs.pm/feederer/

  1. ↩