Ex_doc: Add option to link to lastest MINOR and PATCH versions of documentation in hexdocs.pm

[eksperimental]

One nuisance I have have across multiple times when reviewing the Phoenix documentation is I noticed they link directly to the stable version of the documentation using a custom link (i.e. https://hexdocs.pm/ecto/Ecto.html), instead of just using backticks and let Exdoc generate the link to the version of the package installed when the docs were generated (i.e. https://hexdocs.pm/ecto/3.5.0/Ecto.html)

I think it will be useful to have an option such as link_to_stable_doc, or link_to_latest_doc which can accept either :all or a list with the package names [:ecto, :earmark].

That will simplify writing documentation.

[josevalim]

This is complicated because we don't know if the module exists on the latest version of the docs. For example, what if a project is linking to Ecto v2.0 and now there is Ecto v3.0? Having an option pushes this decision to the user but it doesn't really stop the issue from happening. At the same time I understand your pain.

Something that would alleviate my concern is if we could make the not found page on hexdocs.pm smarter. Maybe it could try to find if any package version contains the given module? Without this, I wouldn't be comfortable with this change.

[eksperimental]

Then we should never link to a different major version, which will also make sense. And if someone wants that, they will have to use custom links as we are doing now.

From the hexdocs.pm side what we could do is redirect:
MAJOR.MINOR links such as https://hexdocs.pm/ecto/3.5/Ecto.html redirect to the latest version for that MINOR (https://hexdocs.pm/ecto/3.5.8/Ecto.html), but if this latest version is the stable version, redirect to the stable version . https://hexdocs.pm/ecto/Ecto.html

Same with MAJOR, https://hexdocs.pm/ecto/3/Ecto.html ~links~ redirects to https://hexdocs.pm/ecto/3.5.8/Ecto.html but if is the the stable version it redirects to https://hexdocs.pm/ecto/Ecto.html

And from our side we could set: :link_to_latest_patch_version_doc, :link_to_latest_minor_version_doc,

[wojtekmach]

Phoenix cannot use `Ecto` because it doesn't depend on Ecto.

As you mentioned if someone uses back tics it would generate a URL with the version that you happen to be using right now, if you use a custom link then we'd use the URL of the custom link. Thus I don't think we need to introduce new options as the current system is pretty flexible, isn't it?

[eksperimental]

Phoenix cannot use `Ecto` because it doesn't depend on Ecto.

I am not following what you mean.
https://github.com/phoenixframework/phoenix/blob/dee4798642901c401c60757ce86277761633ff03/mix.exs#L76

[wojtekmach]

Oh, didn't know they do that!

OK I think I get what you want to achieve, you want to be able to write `Ecto` and make that generate a URL to stable instead of URL to versioned. I suppose we could do that, but because we can achieve it using a custom link that's good enough to me and I wouldn't complicate things.

[eksperimental]

Thus I don't think we need to introduce new options as the current system is pretty flexible, isn't it?

It is flexible, I am not arguing that. But it leads to having to replace external links every time you want to link, and if you forget some the docs are inconsistent.

[wojtekmach]

Why does Phoenix write [`Ecto`](https://hexdocs.pm/ecto/Ecto.html) instead of `Ecto`? What's wrong with generating a versioned URL?

[eksperimental]

Why does Phoenix write [`Ecto`](https://hexdocs.pm/ecto/Ecto.html) instead of `Ecto`? What's wrong with generating a versioned URL?

I haven't asked. I assume it is because they want their documentation to link to the most up-to-date documentation. It makes total sense linking to the latest PATCH version. It is arguable linking to a different MINOR version. It is probably be wrong to link to the latest stable version.

[josevalim]

It is most likely the reason is that they were written before ExDoc supported cross deps linking.

[wojtekmach]

But then it wouldn’t make sense it has :ecto, only: :docs :) but probably both is true, some docs were written before and some after exdoc had such support.

[eksperimental]

Another thing that we can do is rely on the version requirements of the dependencies, and determine whether to link to the exact version, their latest patch, or minor.
config would be :link_to_lastest_doc
In case a dependency has the the requirement "> 1.0.0", we can link to the latest stable, but we need to explicitly set it in a config with an additional setting such as :link_to_latest_stable_doc.

I like this option :link_to_lastest_doc, because it is just a flag, and let ExDoc do all the logic.

[josevalim]

The problem is to know what latest stable means. We don’t know this when generating the docs (unless we start coupling to Hex). We could add a feature to Hex though to ask it to redirect to the latest of a given requirement. So once again, I don’t see how we can implement this without adding features to other places that are not under our control.

[eksperimental]

The problem is to know what latest stable means. We don’t know this when generating the docs (unless we start coupling to Hex). We could add a feature to Hex though to ask it to redirect to the latest of a given requirement. So once again, I don’t see how we can implement this without adding features to other places that are not under our control.

Well, All this said if https://github.com/elixir-lang/ex_doc/issues/1341#issuecomment-791962561 could be implemented.
I haven' t look into Hex's source code. But I am sure this is already implemented because of the feature that lists all the versions in the dropdown in the sidebar. We will just need to add 2 redirection rules for /X/ and /X.X/

The problem is to know what latest stable means.

This is already solved by Hex. It is the URL without a version in it.

[eksperimental]

I will work on a PR for hexpm with said feature and come back here

[josevalim]

Yes, I am aware it is available, but it is not exposed in a way we can consume.

I don’t think the feature should be done with hexdocs redirects. Rather, something like this:

Hex.pm/redirects/latest/hexdocs/ecto?requirement=...

[eksperimental]

Yes, I am aware it is available, but it is not exposed in a way we can consume.

I don’t think the feature should be done with hexdocs redirects. Rather, something like this:

Hex.pm/redirects/latest/hexdocs/ecto?requirement=...

and that would return a version, a URL, or just redirects you to said URL?

[josevalim]

It just redirects to the highest version matching a requirement.

[eksperimental]

It just redirects to the highest version matching a requirement.

great. I will take care of it.

[josevalim]

Thanks! I will go ahead and close this, as it requires elsewhere and I think we have more important issues to tackle in our issues tracker.