Custom links to modules

[wojtekmach]

Ref: #679 (comment)

     assert project_doc("[`Registry docs`](`Registry`)", %{docs_refs: []}) ==
       "[`Registry docs`](https://hexdocs.pm/elixir/Registry.html)"

     Assertion with == failed
     code:  assert project_doc("[`Registry docs`](`Registry`)", %{docs_refs: []}) == "[`Registry docs`](https://hexdocs.pm/elixir/Registry.html)"
     left:  "[[`Registry`](https://hexdocs.pm/elixir/Registry.html)](https://hexdocs.pm/elixir/Registry.html)"
     right: "[`Registry docs`](https://hexdocs.pm/elixir/Registry.html)"
     stacktrace:
       test/ex_doc/formatter/html/autolink_test.exs:262: (test)

[fertapric]

This kind of syntax doesn't work well with command line tools like IEx. This is how the given example would appear in IEx:

And this is how it would appear if we do not support this syntax:

I would favor readability of the documentation in all formats 🙂

[fertapric]

As a side note, I would have written it as:

`Registry` docs
the documentation for `Registry`

which is auto-linked by ExDoc and rendered in IEx as:

Registry docs
the documentation for Registry

In IEx, users can simply use h/1 to get further information.

Edited: there was an error in how IEx would render the docs. Thanks @wojtekmach

[wojtekmach]

not sure, I thought that IEx doesn't know about hexdocs.pm and can't generate these links.

But I think you're right, we probably don't need custom links for modules, I thought it could be an intermediate step to #910 which I think would be nice and if that sounds good we should work on just that instead.

[fertapric]

@wojtekmach You are right. I edited my previous comment :)

[eksperimental]

This kind of syntax doesn't work well with command line tools like IEx. This is how the given example would appear in IEx:

And this is how it would appear if we do not support this syntax:

I would favor readability of the documentation in all formats

I have mixed feelings about this. While in theory, you will be able to see the URL in IEx, in practice you will still see the Module name, because people will not rememeber that you can use Custom links for everything but for Mix tasks and modules names.
If that's the case we should drop custom links all together.

As I am working in another PR, I wanted to write:

Some tasks are automatically reenabled such as: [`cmd`](`mix cmd`),
  [`do`](`mix do`), [`loadconfig`](`mix loadconfig`),...

But I realize Mix tasks does not support custom links, so what should I do here? use the URL?

[josevalim]

I would write it as:

Some tasks are automatically reenabled, such as: mix cmd, mix do, ...

I don't think the complexity it adds on the doc itself and on the command line justifies the shortcut to emit the mix part.