trivelop   home of @rrrene   –  

Continous Documentation of Elixir packages with Hex and Travis CI

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):

Inch CI

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.

Inch CI: Can I have Elixir badge?

The short answer is: Yes. After the release of version 0.5.0, we now have multi-language support in Inch and therefore Inch CI badges for Elixir were in reach.

The great news is: The Phoenix Framework accepted my proposal to include a docs badge in its README and both Chris McCord and José Valim were supportive of the idea.

This is how the badge looks like:

Inline docs

It shows an assessment of the inline-docs of a project. Its intention is to show aspiring Elixirists (is that a word?) that documentation is a first class citizen in Elixir. It does not display coverage numbers, but gives visitors a visual feedback that your project is not completely undocumented (it is more like "Yep, there seems to be a nice amount of docs" rather than "61.5% documented").

You can read about why Inch does not use percentages and the value of the docs badge for maintainers in earlier posts.

Okay, now how can I add my own project?

Building Elixir projects for Inch CI relies on your testing CI server to compile your Elixir app. Typically this will be Travis, so let me show you how it is done:

First, you have to include inch_ex in your dependencies in the mix.exs file:

  defp deps do
    [{:inch_ex, only: docs}]
  end

Your .travis.yml might look something like this:

  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 --only test
  script: mix test

Simply add the following at the end of the file:

  after_script:
    - MIX_ENV=docs mix do deps.get, inch.report

What this does is that your docs are evaluated at the end of your next Travis build. Travis sends a report to Inch CI which then displays the results here (and generates a new badge for you).

Feedback on all of this is always welcome. Reach out via Twitter, create an issue in the Inch CI project or simply email me (mail in Github profile).

Inch 0.5.2 released

Inch

After 11 release candidates (yeah, I know) we finally got to Inch 0.5.

It has always been my goal to apply Inch's mechanics to other languages besides Ruby (which does not mean Ruby support was neglected in this release, see CHANGELOG for more info), so the exciting news is that this release contains the necessary refactorings to support more languages besides Ruby. Specifically, it brings Elixir support via InchEx. Furthermore, all of this has the potential to be integrated into Inch CI in the future.

InchEx

InchEx is a wrapper to use Inch with an Elixir codebase. It provides Mix tasks to use Inch for Elixir codebases without having the Ruby dependencies installed. Later it will be used to report stats to Inch CI. The plan is to provide badges for READMEs, just as we did with Ruby:

Inline docs

I am really excited about these releases, as they lay the ground work for an interesting future for Inch and Inch CI. Thanks to all contributors and bug reporters for their feedback and hard work!

P.S. Inch CI breached 350 projects using its badges this morning! Yay!

P.P.S. Trying to start a discussion about the integration of Elixir into Inch CI.

Fork me on GitHub