Generate docs for Erlang projects

[erszcz]

Hi! This PR fixes some small issues when generating docs from Erlang doc chunks (created by erl_docgen or edoc). These are mostly earlier @wojtekmach's changes and my fixes from #1143, applied on top of the current master.

This PR also exposes the ExDoc.Config.proglang field as a command line switch --proglang. This way it's possible to determine which (Elixir, the default, or Erlang) stylesheet is used for the generated documentation. This might not be flexible enough for projects shipping both Erlang and Elixir APIs, but seems to be a good enough starting point.

A preview of a trivial lib's docs is available at https://erszcz.github.io/kvs.

Currently, the prerequisite to generate Erlang docs is having EDoc with EEP-48 support installed - either as a standalone app from https://github.com/erszcz/edoc or from erlang/otp#2803. With that in place:

$ PATH_TO_EDOC/bin/edoc.escript -app kvs -chunks -pa _build/default/lib/kvs/ebin
$ PATH_TO_EXDOC/bin/ex_doc kvs "0.1.0" _build/default/lib/kvs/ebin/ --main kvs -o ex_doc --proglang elixir

[wojtekmach]

@erszcz great, thank you! It's marked as WIP so please let us know when you think it's ready to be merged in - we don't have to solve everything in this one PR of course, but if we can find an incremental step and merge that, I think that's a good path forward.

Regarding having to use your EDoc branch, I was able to find a workaround. It might be using private code so take it with a grain of salt. Here's generating chunk for foo module in ex_doc app:

$ app=ex_doc; \
  module=foo; \
  app_dir=_build/dev/lib/$app; \
  xml_dir=$app_dir/doc/xml; mkdir -p $xml_dir; \
  chunks_dir=$app_dir/doc/chunks; mkdir -p $chunks_dir; \
  erl_docgen_dir=$(erl -noshell -eval 'io:format("~s", [code:lib_dir(erl_docgen)]), halt()'); \
  escript $erl_docgen_dir/priv/bin/xml_from_edoc.escript -dir $xml_dir src/$module.erl; \
  escript $erl_docgen_dir/priv/bin/chunk.escript $app $app_dir/ebin "" $chunks_dir/$module.chunk

[erszcz]

Hi @wojtekmach!

Regarding having to use your EDoc branch, I was able to find a workaround. [...]

Clever! I’ll have to see how these compare with EDoc chunks - I guess they might be missing callback docs, but I’m not sure right now.

It’s marked as WIP [...]

First, I was interested in your approach to exposing proglang as a CLI switch, but I understand you’re fine with that.

Then, we have the problem with tests. The failing test is 3rd party links, but in mix test context (or MIX_ENV=test iex -S mix), test_module is actually part of ExDoc:

$ MIX_ENV=test iex -S mix
iex(1)> :application.get_application(:test_module)
{:ok, :ex_doc}

This is consistent with the module’s comment in test/support/test_module.ex, which suggests it would more accurately fit into poject-local module, even though it’s an Erlang one.

I guess this should be explored further, since we can expect links to project-local Erlang modules (rare, I guess, though elixir itself is an example of such an app), or 3rd party Erlang modules (projects completely in Erlang; I expect this to be much more common, e.g. telemetry and Telemetry.Metrics). I see no reason not to link to standalone Erlang projects on HexDocs the same way Elixir docs are linked to.

In the scope of this PR, though, I propose to distinguish between Erlang OTP and non-OTP modules and only link to OTP docs. This does not introduce functionality changes and therefore carries no changes in tests.

[erszcz]

I'm now a bit puzzled with the CI results of 390c561. When run locally, the first mix test run fails, but subsequent runs pass as expected. Troubleshooting...

[erszcz]

@wojtekmach I've removed the WIP label. I think this is now ready to merge or review further if you see anything fishy :)

[wojtekmach]

@erszcz after #1329 lands, we'll have basic support on master! This is how it'll look like: http://wojtekmach.pl/docs/stdlib/api-reference.html. We still have some internal changes to do before we even introduce the language contract, but we're very close. Then we'd cherry pick things from this PR. THanks!