Can't generate Erlang library documentation using ExDoc

[kianmeng]

Running on Erlang: 24.0.2
Erlang library tested: https://github.com/certifi/erlang-certifi

I was following the instruction here, https://github.com/elixir-lang/ex_doc#using-exdoc-with-erlang-projects, but stuck at step 4.

rebar.config as follows:

{erl_first_files, ["src/certifi_pt.erl"]}.

{erl_opts, [deterministic  %% Added since OTP 20
           ,{platform_define, "^2", 'OTP_20_AND_ABOVE'}
           ,{doclet, edoc_doclet_chunks}
           ,{layout, edoc_layout_chunks}
           ,{dir, "_build/default/lib/certifi/doc"}
           ]}.

To generate doc using rebar3:

rebar3 edoc

No issue, works just fine:

To generate doc using ExDoc:

rebar3 compile # <-- missing this step here otherwise `_build/default` folder is not found
ex_doc "certifi" "2.7.0" _build/default/lib/certifi/ebin

HTML files were generated, but without the content?

Not familiar with Erlang and its ecosystem, did I miss out something?

[wojtekmach]

Did you follow all the steps from the readme, in particular changingrebar.config to use edoc chunks and changing certifi.app.src too?

[wojtekmach]

Please use edoc_opts, not erl_opts for edoc stuff

[kianmeng]

@wojtekmach I still not generating the api doc when running:

$ rebar3 edoc
===> Verifying dependencies...
===> Analyzing applications...
===> Compiling certifi
===> Running edoc for certifi

$ ex_doc "certifi" "2.7.0" _build/default/lib/certifi/ebin/

The diff of my changes, https://github.com/certifi/erlang-certifi/compare/master...kianmeng:gen-doc-with-exdoc?diff=split

[michallepicki]

Hitting the same issue with a different library (sesterl_stdlib) - following commands from README results in generated documentation being empty.

I added:

{edoc_opts, [
  {doclet, edoc_doclet_chunks},
  {layout, edoc_layout_chunks},
  {dir, "_build/default/lib/sesterl_stdlib/doc"}]}.

versions:

ex_doc 0319ace
erlang 24.0.6
rebar 3.16.1 on Erlang/OTP 24 Erts 12.0.4
Elixir 1.13.0-dev (d1d8c52) (compiled with Erlang/OTP 24)

Edit: I'm probably doing something wrong though, rebar3 edoc also builds an empty index in my case.

Edit2: With {source_path, ["_generated", "src"]}, in edoc_opts one module shows in edoc-generated html (only one though). In ex_doc generated html still no modules show up.

[josevalim]

Can you please compare your setups with the one in beam-telemetry/telemetry? That one is working for sure, so maybe it can help :)

[michallepicki]

The only differences I see are:

• setting edoc_opts in a docs profile instead of on top level
• {preprocess, true} option being set which expands erlang macros

I made those changes and generated html is still empty - I don't think they make a difference in that case.

Here are steps to reproduce with erlang-certifi (it's probably a better test case):

$ git clone git@github.com:kianmeng/erlang-certifi.git
$ cd erlang-certifi
$ git checkout gen-doc-with-exdoc 
$ rebar3 compile
===> Verifying dependencies...
===> Analyzing applications...
===> Compiling certifi
$ rebar3 edoc
===> Verifying dependencies...
===> Analyzing applications...
===> Compiling certifi
===> Running edoc for certifi
$ ex_doc "certifi" "2.7.0" _build/default/lib/certifi/ebin
# open doc/index.html and see it's empty

[kw7oe]

Hi all, I have briefly look into this issue and able to generate the Erlang docs successfully by applying this following diff. It appears that ExDoc requires documentation on the top level module to be able to generate it successfully. I might be wrong tho.

diff --git a/src/certifi.erl b/src/certifi.erl
index 6280642..93e44c7 100644
--- a/src/certifi.erl
+++ b/src/certifi.erl


@@ -1,3 +1,7 @@
+%% @doc
+%% Certifi Module
+%% @end
+
 -module(certifi).
 -compile({parse_transform, certifi_pt}).
 
@@ -24,4 +28,4 @@ cacertfile() ->
 %% passed to the connect function.
 -spec cacerts() -> [binary(),...].
 cacerts() ->
-    ok.
\ No newline at end of file
+    ok.
diff --git a/src/certifi_pt.erl b/src/certifi_pt.erl
index 4eecb89..1403102 100644
--- a/src/certifi_pt.erl
+++ b/src/certifi_pt.erl
@@ -1,3 +1,7 @@
+%% @doc
+%% Certifi PT module.
+%% @end
+
 -module(certifi_pt).
 -export([parse_transform/2]).

See screenshots as result of fixes:

[michallepicki]

So in elixir modules one has to explicitly set @moduledoc false but in Erlang modules this is assumed default? So it could be either

1. edoc setting the doc chunks wrongly
2. ex_doc interpreting the missing information wrongly
3. ambiguity and behavior not specified in EEP

[josevalim]

Awesome find @kw7oe! 💯

@michallepicki I don't think this is a wrong setting. It is rather a difference of defaults: edoc legit considers everything not explicitly doc-ed as private, Elixir has a different perspective. The EEP does not say what the defaults should be, only how values should be stored. I will update the docs!

💚 💙 💜 💛 ❤️

[michallepicki]

edoc legit considers everything not explicitly doc-ed as private

If that would be the case, wouldn't those modules be hidden in html documentation generated by edoc?

[josevalim]

Oh, you are 100% correct. I missed that. Let's bring in the big guns: @erszcz :)

[josevalim]

@erszcz I believe I found the root cause:

https://github.com/erlang/otp/blob/master/lib/edoc/src/edoc_layout_chunks.erl#L452

I think it should return an empty map, otherwise it gets the same treatment as edoc's @private. WDYT?

[josevalim]

@michallepicki I think I mixed the edoc behaviour with Erlang/OTP's XML behaviour. In Erlang, they consider everything not explicitly doc-ed as private. But don't hold that against me because now I am not sure. Thanks for catching it.