Rebar3_ex_doc - a rebar3 plugin for generating documentation using ex_doc

Your Libraries & OS Mentoring Libraries
, , , ,
1

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:

14 Likes
2

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
3

And how the docs looks when they are generated.

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

6 Likes
4

Looks nice!

4 Likes
5

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

4 Likes
6

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
7

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

4 Likes
8

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
9

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
10

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
11

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

4 Likes
12

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
13

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
14

@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
15

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

2 Likes
16

they appear in the documenation, but I can’t add any text to it’s documentation, like for example:
https://hexdocs.pm/ecto/Ecto.Repo.html#c:default_options/1
https://hexdocs.pm/ecto/Ecto.ParameterizedType.html#t:params/0

1 Like
17

Try this for types… (works for me)

-module(mylib).

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

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

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

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

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

rebar3_ex_doc - 0.2.13 was released.

This release merely upgrades ex_doc to 0.28.5.

Enjoy :smile:

3 Likes
19

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

Enjoy :slight_smile:

2 Likes