Rebar3_ex_doc - a rebar3 plugin for generating documentation using ex_doc

rebar3_ex_doc - A rebar3 plugin for generating documentation using ex_doc

This plugin uses edoc to generate doc chunks and ex_doc to craft both html and epub outputs.

It should be duly noted that this functionality is thanks to many peoples efforts around EEP-48 and not the plugin.

In the EEF build and packaging working group we have been planning to make said functionality, which has existed for a while now, available via a rebar3 plugin.

rebar3_ex_doc makes it easy to get up and going. Perhaps more importantly, it serves as a doc provider for rebar3_hex, which further paves the way towards a more consistent documentation format and style for erlang packages on

The configuration required to get going is extremely minimal, you can read about it in the docs.

Feel free to open issues or PRs here

Huge shout out to tank-bohr who graciously donated ownership of the existing rebar3_ex_doc package on :clap: :clap: :clap:


Great work! :mechanical_arm: I just wanted to start creating a similar plugin on this week… but it looks like you got ahead of me :upside_down_face:.


And how the docs looks when they are generated.


Looks nice!


Awesome work y’all! I love the small detail of how rebar_ex_doc already has the new documentation format :slight_smile:


I tried this on an umbrella codebase and it struggled due to modules with an explicit include path to another application. I’m not at work, but I’ll try to give an example:

   |  +--include
   |  |  +--app1.hrl
   |  +--src
   |     +--app1.erl

This is fine for compile, ct, xref, dialyzer, elvis, hank - the usual suite. Also fine for edoc. However, with rebar3 ex_doc I get:

can't find include file "apps/app1/include/app1.hrl"
edoc: error in doclet 'edoc_doclet_chunks': {'EXIT',error}.

(Raised as Can't find include file in an umbrella project · Issue #3 · starbelly/rebar3_ex_doc · GitHub)


This is just awesome! Thanks and congratulations to all contributors! :clap:


Thank you for opening the issue :heart:

This is a great find! I can replicate this in rebar3_ex_doc but more importantly using edoc as well. It seems to be around when {preprocess, true} is set.


rebar3_ex_doc v0.2.5 has been released :partying_face:


Updated to ex_doc 0.27.2 which brings a new shiny set of formats and styles for docs. See the announcement by José here :

Check out the updated look for erlang docs : rebar3_ex_doc v0.2.5 — Documentation

Bug fixes

  • Fixed a bug that prevented generating docs on windows thanks to cw789 for raising the issue and testing the patch (this was actually released in 0.2.4, but noting here).
  • Fixed a bug where by we were not passing the package name to ex_doc
  • Fixed a bug where by edoc opts along with ex_doc_opts might cause beam chunks to not be emitted (this was actually fixed in 0.2.3, but noting here). Thanks to @Taure for raising the issue.

rebar3_ex_doc v0.2.6 has been released :partying_face:


  • Updated to ex_doc 0.27.3
  • Added -e/–ex-doc switch so you can specify a path to an alternate version of an ex_doc escript
  • Improved docs and added Changelog thanks to Kian-Meng Ang

More in the changelog


About changelog, you can take a look at my systemd or mix_unused where I generate changelog automatically out of commit messages.


Release 0.2.7 seems broken, it doesn’t contain priv/ex_doc anymore and the changelog has an [Unreleased] entry instead of [0.2.7]. Did you publish this one accidentally?


Not accidentally, but made an accident. It’s been long enough I had do a new release - 0.2.8.

0.2.8 includes an enhancement that adds deps to ex_doc path such that referenced types from deps won’t result in a warning.


@starbelly I understand that it uses the same tags as edoc.
is there a way to document types and callbacks? :thinking:
I was reading edoc chapter, and didn’t find anything about it.

1 Like

Documentation for types, as stated in EDoc’s Type specifications, is generated out-of-the-box (nothing special to it). Take a look at this example, from Nova: nova — nova v0.9.4.

Callbacks are exported functions, so should be there also. Take a look at this example, from gen_smtp: gen_smtp_server_session — gen_smtp v1.2.0


they appear in the documenation, but I can’t add any text to it’s documentation, like for example:

1 Like

Try this for types… (works for me)


-type a() :: {a, 2}. %% So I want to document stuff,
%% and I want it to be multi-line.
%% Right?

-type b() :: {b, 2}. %% How should I do it?
%% Can you help?

-export([a/0, b/0]).

%% @doc Would this work?
-spec a() -> ok.
a() ->

%% @doc What's this about?
%% e.g. with multi-line
-spec b() -> not_me.
b() ->

rebar3_ex_doc - 0.2.13 was released.

This release merely upgrades ex_doc to 0.28.5.

Enjoy :smile:


rebar3_ex_doc 0.2.14 has been released :partying_face:

What’s Changed

New Contributors

Full Changelog: Comparing v0.2.13...v0.2.14 · starbelly/rebar3_ex_doc · GitHub

For more information on cheatsheets check out Jose’s tweet about cheat sheet support :

Enjoy :slight_smile: