Continous Documentation of Elixir packages with Hex and Travis CI

Hex 0.6.0 (Elixir's package manager) is out and it includes "mix hex.docs" which pushes your beautiful docs to hexdocs.pm!

— José Valim (@josevalim) October 14, 2014

So you can now publish the docs for your Elixir package with

$ mix hex.docs

That’s it. That is crazy simple. One command and they are online. But we can make it even simpler: Let’s delegate the publishing duties to Travis CI.

There are two things we have to do for that: Configure our Hex account in the Travis build and advise Travis to publish our docs for us.

The rest of the post assumes you have published docs for a Hex package before. If you haven’t, please read this introduction.

1. Putting your Hex credentials into Travis

First, we have to retrieve the information we want to put into our Travis builds:

$ mix hex.config username
"rrrene"

$ mix hex.config key
"3J98t1WpEZ73CNmQviecrnyiWrnqRhWy"

These are our username and password for interacting with Hex. We will use these to tell Travis to publish our docs.

Next, we go to our repo’s Travis page and into “Settings” and then click the tab “Environment Variables”. Here, we add two variables: HEX_USERNAME and HEX_KEY with the output we got above (minus the quotes):

2. Configuring Travis to do our job

Finally, we have to modify .travis.yml and add an after_script: section:

language: erlang
otp_release:
  - 17.1
before_install:
  - wget http://s3.hex.pm/builds/elixir/v1.0.0.zip
  - unzip -d elixir v1.0.0.zip
before_script:
  - export PATH=`pwd`/elixir/bin:$PATH
  - mix local.hex --force
  - mix deps.get
script: mix test
after_script:
  - mix hex.config username $HEX_USERNAME
  - mix hex.config key $HEX_KEY
  - mix hex.docs

This publishes our docs with the username/key combination we configured, continously.

Using worker: worker-linux-10-2.bb.travis-ci.org:travis-linux-22

...

Generated inch_test.app
Docs successfully generated.
View them at "docs/index.html".
[#########################] 100%
Published docs for inch_test v0.0.1
Hosted at http://hexdocs.pm/inch_test/0.0.1/
Done. Your build exited with 0.

If you like, let’s have a chat about this on Twitter.