Proposal: mix docs.local to build and include all of our deps docs too

[jeregrine]

Let me know if this unwelcome or better served by hex docs or something that would be better served as a third party dep, or if this has been discussed before and I missed it.

Problem

As elixir grows and our dep tree's grow deeper and deeper it can become a hassle to figure out where a function specifically lives and read its documentation.

A good example is Phoenix a function that is imported by default can come from:

• liveview
• phoenix_ecto
• phoenix_html
• plug
• phoenix

Which can make discoverability difficult, and requiring jumping between hexdoc pages.

Alternatively you can use iex which has all of these docs generated and in-code already.

I also know you can manually do "mix hex.docs.offline <PACAKGE>" to get individual packages locally, its just not very useful outside of individual packages.

Proposed Solution

A version of mix docs.local that generates one "mega docs" that includes all of your project docs and the docs of every dep in one html page.

and an 'mix docs.local --open' that opens your browser right up to the index.

Inspiration

cargo doc: https://doc.rust-lang.org/cargo/commands/cargo-doc.html

This command by default will build your docs and all of your dependencies and give you a single html page to visit to search/read all of them at the current version you have in your deps.

Here is a screenshot of what opens up when you type cargo doc --open from a popular open source project 'bevy'

Most of the "magic" happens in the sidebar:

• Your Application docs at the top
• Then each dep listed below. Clicking on one shows you its full doc and Readme.
• The search is unified a crossed the entire tree.

[josevalim]

A PR to add something like mix deps.docs would be very welcome!

[wojtekmach]

Let's start with the use case at hand but later on I think it might be interesting for the docs for Elixir itself since it is split between elixir, mix, logger etc. I think it would be cool to autocomplete Mix functions from Elixir docs and vice versa.

[josevalim]

Yes, I think there are two use cases here. Mixing search items for Phoenix/Elixir and the local one. Feel free to open up an issue for the search one @wojtekmach.

[jeregrine]

@josevalim I will tinker on this, maybe I can use some iframes to get a basic setup working first.

FOR SOME REASON I thought livebook was doing something like this for all Mix.install'd deps but realizing now it was just the autocomplete.

[josevalim]

I think no iframes are necessary. You can pass multiple paths for us to generate the docs from. So you can pass the ebin paths of your dependencies and it should generate the docs for everything at once. So all of the infrastructure is likely in place already.

[josevalim]

See #1593.