Generating both Erlang and Elixir docs at once

[whatyouhide]

The OpenTelemetry projects often expose both an Erlang and an Elixir API. Right now, unless I’m missing something, it's pretty cumbersome to expose docs for both via ExDoc.

Let's take opentelemetry_telemetry as an example. It exposes just a single Elixir module (OpentelemetryTelemetry) and one Erlang module (otel_telemetry). It has a mix.exs config file as well as a rebar.config file.

You can see what I’m talking about because the generated docs on hexdocs.pm are only for the Elixir module: https://hexdocs.pm/opentelemetry_telemetry/OpentelemetryTelemetry.html

I wanted to open this issue to:

• Chat about this async
• Understand if I’m missing something and there's an easy way to do this
• Brainstorm how we can streamline this workflow

Thanks for the time!

[wojtekmach]

opentelemetry_api has docs for both languages:

https://hexdocs.pm/opentelemetry_api/OpenTelemetry.Span.html
https://hexdocs.pm/opentelemetry_api/otel_span.html

So I believe it’s just a matter of configuration.

[josevalim]

It is also worth noting that this should work out of the box with Erlang/OTP 27 and the new docs. Previous Erlang versions require a rebar3 plugin, which makes it too much work for us to support out of the box (but it is possible as long as configuration is provided)

[whatyouhide]

opentelemetry_api has docs for both languages

@wojtekmach I’m aware, but the setup is pretty non-intuitive. I cannot, for the life of me, reproduce this consistently. It seems to be a combination of:

1. rebar3 compile + rebar3 edoc to get stuff into _build/default/lib/opentelemetry_api/ebin
2. mix deps.get + mix compile, to get stuff into _build/dev/lib/opentelemetry_api/ebin
3. This call to ExDoc:

   ex_doc "opentelemetry_api" $api_version "apps/opentelemetry_api/_build/dev/lib/opentelemetry_api/ebin" \
     --source-ref v${exp_api_version} \
     --config apps/opentelemetry_api/docs.config $@ \
     --output "apps/opentelemetry_api/doc"

Not sure how this works given rebar shoots stuff into _build/default but Mix in _build/lib.

It is also worth noting that this should work out of the box with Erlang/OTP 27 and the new docs

Perfect.

Previous Erlang versions require a rebar3 plugin, which makes it too much work for us to support out of the box

Folks, I’m not arguing to add this to ExDoc now 🙃 It would be a great addition to document how to do this now, with the Rebar plugin and whatnot, given it's really not trivial IMO. I think that would be beneficial anyway, because OTP 27 is a couple months away and not everybody will be able to update and switch to the new Erlang doc format right away. Thoughts?

[josevalim]

OTP 27 is a month away (probably less). We would accept contributions to document this but it is unlikely we will invest effort given a better more integrated mechanism will be available within a month. I understand migrating to OTP 27 may be hard for applications but for most libraries it should be straight-forward.