Add an endpoint handling Scaladoc linking

pikinier20 commented 2 years ago

The idea is to add some endpoint that for given library and member coordinates:

case class Library(
  org: String,
  lib: String,
  version: String
)
case class DRI(
  location: String,
  anchor: String
)

redirects to the documentation of the member. It should be aware of which version of Scaladoc it links to.

julienrf commented 2 years ago

@pikinier20 In the web interface, we show a “Scaladoc” link that points to the scaladoc URL of the given artifact (it defaults to javadoc.io, but users can override it).

Screenshot from 2022-01-10 16-15-07

Do I understand well that this is this link that you would like to retrieve via the endpoint? Could you please give more details about the response model you suggest in the issue description? What are “location” and “anchor”?

pikinier20 commented 2 years ago

To be precise, I would like to retrieve this link + link to member inside this documentation. So, I would like to pass information to Scaladex like: Library( "org.virtuslab", "scala-cli", "0.0.9" ) DRI( "runner/SomeRunner" "run-..." ) and have a link to documentation of scala-cli pointing on the method run in class SomeRunner. The DRI model is the same as we use in Scaladoc and actually basing only on it and a kind of documentation (whether it's Scaladoc 2, 3 or some Javadoc) we can construct a valid link to member.

We had a discussion about the way Scaladex retrieves documentation location. Sbt has an option to attach the location of documentation to POM (then uses this information when autoAPIMapping is enabled) and we could extend this option to add there a version of Scaladoc. Scaladex might want to use this information.

adpi2 commented 2 years ago

I deployed a new scaladoc endpoint in the dev environment: https://index-dev.scala-lang.org

The template of this endpoint is:

https://index-dev.scala-lang.org/artifacts/<group-id>/<artifact-id>/<version>/scaladoc<optional-path>

where <optional-path> can contain a path (e.g., /api/io/iteratee/Enumeratee.html), an anchor (e.g., #io.iteratee.Enumeratee) or both.

Examples:

It also works with Scala.js or Scala Native:

https://index-dev.scala-lang.org/artifacts/io.iteratee/iteratee-core_sjs1_2.13/0.20.0/scaladoc/io/iteratee/Enumeratee.html

Note that the client (here it would be scaladoc) must know the <optional-path> depending on the library dependency. If it is a Scala 3 dependency it must starts with /api but not if it is a Scala 2.13 dependency.

@pikinier20 I would be happy to have your feedback on this initial implementation before we freeze it and deploy to prod.

scalacenter / scaladex

Add an endpoint handling Scaladoc linking #749