Expose option for unified docs generation for umbrella projects

[ecpeterson]

I'd like to be able to generate unified documentation for an umbrella project, which rebar3_ex_doc currently expressly disallows. It would be nice if it merely hid this underlying ex_doc functionality behind a flag (e.g., --umbrella), disabled by default.

https://erlanger.slack.com/archives/C055DJA49/p1727628889072409

[starbelly]

I think this is a good idea. I think we just need a switch as indicated above, --umbrella makes sense, unless there's a switch name that could be thought of that indicates the intention more clearly (i.e., we already compile for umbrellas, but we don't unify the output).

I think what would work here is if this switch is passed :

1. Make a _build dir at the root of the umbrella
2. Build chunks for all apps with an output dir of _build/docs at said root.
3. Emit a docs.config and/or use switches to indicate the path and the main app name

That may be an oversimplification, but at a glance I think this would work. What's more, we can double back and check for this option in rebar3_hex and exit with an error if it passed.

https://github.com/elixir-lang/ex_doc/blob/fe9eeebf09f3d810e98dba8e611355ae163f4f06/lib/mix/tasks/docs.ex#L447

Edit:

P.S. A PR would greatly be appreciated, otherwise an existing contributor will get to it when we can / feel the inclination

[ecpeterson]

I'll try to make an attempt soon. Happy to change the flag name if we come up with a better one; that's hardly blocking.

[paulo-ferraz-oliveira]

Is it possible to package/publish from an umbrella, though? Because that's the feature request behind the feature request, right?

[ecpeterson]

This might incite someone else to ask for that, but I'm only after internal documentation and don't have any plans of my own to publish from an umbrella.

[paulo-ferraz-oliveira]

Ah, if it's only for internal documentation (you hadn't stated the use case) it might be simpler, yes.