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 hex.pm.

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 hex.pm :clap: :clap: :clap:

13 Likes

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

3 Likes

And how the docs looks when they are generated.

https://hexdocs.pm/nova/nova.html

6 Likes

Looks nice!

4 Likes

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

4 Likes

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:

Project
+--apps
   +--app1
   |  +--include
   |  |  +--app1.hrl
   |  +--src
   |     +--app1.erl
   +--app2
      +--src
         +--app2.erl
-module(app2).
-include("apps/app1/include/app1.hrl").

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)

5 Likes

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

4 Likes

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.

3 Likes

rebar3_ex_doc v0.2.5 has been released :partying_face:

Enhancements

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 : https://twitter.com/josevalim/status/1480815810503495683

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

rebar3_ex_doc v0.2.6 has been released :partying_face:

Enhancements

  • 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

5 Likes

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

4 Likes

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?

3 Likes

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.

5 Likes