Native support for "umbrella" Erlang projects

[robertoaloi]

It is common for Erlang projects to be composed by several distinct applications. This is usually referred to as an umbrella (or release) project. Since ex_doc operates at application level, this means that the user has to figure out a way to produce an index for the project itself.

In the case of a rebar3 project, this is partially solved by the rebar3_ex_doc plugin, which has basic support for umbrella projects. For Erlang projects not using rebar3, this has to be solved case by case.

The most notorious example is Erlang/OTP itself, where an index of all modules is generated here, and a fake index application is defined and used to get the feeling of a single projects. This approach requires custom, duplicated logic for various projects.

Was it ever considered to add native support for umbrella projects to ex_doc itself? I believe it would simplify its usage outside of rebar3 and increase its adoption.

[josevalim]

We can definitely improve support here and we will consider contributions to reduce the amount of code generation on Erlang itself and other projects. However, I think projects should consider generating a single documentation site, if possible, and use the sidebar groups to organize applications. That's because you will get a better search and autocomplete experience if it is all in a single place. Erlang/OTP itself is too large for this to be a viable option though, so they generate several and use solutions like Algolia for search. I am not sure how feasible Algolia is for private docs.

[robertoaloi]

You have a fair point about search. I also agree that generating a single site for a project is the ideal solution here, and that's exactly what I'm trying to achieve. I also just realized that rebar3_ex_doc seems to generate one site per app, so no index there either.

One limitation I found while playing with ex_doc in this context is that ex_doc expects a single ebin directory when invoked. That means that you can only generate one site per application and not a single one per project, unless you fake a single application and do the manual grouping.

[josevalim]

@robertoaloi we would definitely accept PRs so you can pass multiple directories 👍