Link to external types in ExDoc

I recently created my first Hex Package; Ecto.Rut and I’m now working on its documentation. Since it uses Ecto.Repo at the back and returns Ecto.Schema and Ecto.Changeset types, I wanted to link them in the @specs.

Internal and Elixir core types (such as Keyword.t) are automatically linked, but ex_doc doesn’t link external types defined in the Ecto modules. How do I make that happen?

1 Like

I pestered @josevalim on GitHub to make ExDoc link the builtin Elixir pieces when you build docs for your module here:

If you follow the discussion, you’ll see that for now when building your docs, you only get links to your types / modules / functions / etc. and to the builtin Elixir ones but not to other linked apps.

Of course that was almost a month ago, things might have changed, but that’s what I know right now. Hope it helps.

What you are asking for is hard to achieve since there is no common place where documentation is hosted (or at least, nether hex nor exdoc want to enforce them). So you would need something first to tell exdoc the base URL of the other packages docs. Or alternatively build and bundle your dependencies documentation with your own, which again does bloat you documentation for a very minor gain.

So what you are asking for is (currently) not easily possible.

We could add an option where you list [ecto: “”] or even [ecto: :hexdocs] and we would be able to add it as a dependency.

It doesn’t look like it is hard to implement as most of the logic is already there. For example, every time we find a Mod.function/arity in your documentation, we try to find the documentation for it:

lib_dirs is a keyword list with the module ebin directory as key and the documentation as a module. So for example, we know that modules in “/path/to/elixir/lib/mix/ebin” should link to “”.

You can see the lib_dirs we use by default simply contains all elixir apps:

Which are calculated here:

So it seems adding this feature is about adding a new configuration to your mix.exs and then convert it to the lib dirs format. For example, if you specify:

[ecto: ""]

It should become:

[{Application.app_dir(:ecto), ""}]

And then you pass it to the Autolink.all function as argument and concatenate it to elixir_lib_dirs. In fact, we should probably get all dependencies and just assume all of them are on ExDoc. You can configure your own if that’s not the case.

Btw, ExDoc is a very important software for the Elixir community it is always trailing behind in the issues tracker. Contributions are definitely welcome.


Perhaps you can draw some attention through hacktoberfest?

I had some free time today and added this feature to ExDoc v0.14.2. Please give it a try.

The offer for contirbutions still stands though, we still have a dozen of open issues. :slight_smile:


Works perfectly! Thanks!

BTW I also created the ex-doc tag on StackOverflow for ExDoc related questions: