Add Laika API link configuration #462
Conversation
| @@ -85,6 +89,7 @@ object TypelevelSitePlugin extends AutoPlugin { | |||
| override def buildSettings = Seq( | |||
| tlSitePublishBranch := Some("main"), | |||
| tlSitePublishTags := tlSitePublishBranch.value.isEmpty, | |||
| tlSiteApiLinks := tlSiteApiUrl.value.map("*" -> _).toMap, | |||
There was a problem hiding this comment.
Unfortunately the tlSiteApiUrl is not the "base" URL for the API. See (1) in #225 (comment).
So maybe we need to add a tlSiteApiBaseUrl or something ...
There was a problem hiding this comment.
I also wonder if it would be helpful to populate this with some useful defaults. Like for Cats and Cats Effect and stuff, since I assume downstream documentation will want to reference it fairly frequently.
There was a problem hiding this comment.
That's too bad, tlSiteApiUrl worked fine for Cats. Is there a reasonable situation where stripping off everything after the last / wouldn't work? Or only defaulting to tlSiteApiUrl if it ends in / ?
If tlSiteApiBaseUrl would only be used for tlSiteApiLinks, we may as well just have users populate tlSiteApiLinks themselves instead of adding yet another setting.
Is there a way to get those common library versions inside the plugin? I wouldn't want to embed specific versions in the defaults.
There was a problem hiding this comment.
Is there a reasonable situation where stripping off everything after the last
/wouldn't work?
Yeah, so for example http4s-dom sets its tlSiteApiUrl to this, so it "zooms" to the right package.
https://www.javadoc.io/doc/org.http4s/http4s-dom_sjs1_2.13/0.2.6/org/http4s/dom/index.html
So I don't think it would work there.
tlSiteApiBaseUrl can be used to make tlSiteApiUrl and in many cases it will be auto-populated by the unidocs plugin. tlSiteApiUrl wasn't the right primitive.
Is there a way to get those common library versions inside the plugin? I wouldn't want to embed specific versions in the defaults.
Ugh, good point, I forgot about this trickyness. Blah. We could try scouring the classpath for this information but it's a bit hacky. I have to think about this.
There was a problem hiding this comment.
Is there a way to get those common library versions inside the plugin?
Actually, we should try and use the same mechanism that sbt uses for API mappings. These are read out of the dependencies. Essentially Laika is replicating this same feature, we just need to glue them together. This might even be upstreamable into sbt-Laika.
There was a problem hiding this comment.
So have we circled back to providing
tlSiteApiBaseUrlthen?
I think you also have to provide your package as well? Funny enough we might have an existing setting for that.
But I want to think about this more.
There was a problem hiding this comment.
…on the other hand, given the dream is to obsolete most of that config, and it's a one time bit of work on the project being documented, maybe it's best not to add more machinery. here.
There was a problem hiding this comment.
I think you also have to provide your package as well? Funny enough we might have an existing setting for that.
You can provide "*" as an explicit fallback (which is what the case class defaults to) and it handles that specially as a fallback if there is no match. So you don't need to provide your own prefix.
There was a problem hiding this comment.
Right, but what happens if my project is org.http4s.dom and sbt-typelevel had pre-loaded org.http4s API docs for me. It just doesn't work in general.
|
For testing, can we try dog-fooding this in the sbt-typelevel documentation? |
| .withConfigValue(LinkConfig(apiLinks = tlSiteApiLinks.value.toList.map { | ||
| case (packagePrefix, baseUri) => | ||
| ApiLinks(packagePrefix = packagePrefix, baseUri = baseUri.toString) | ||
| })), |
There was a problem hiding this comment.
Does the order here matter? e.g. what happens if the cats prefix comes before the cats.effect prefix?
There was a problem hiding this comment.
Order doesn't matter, Laika uses longest prefix match.
This PR sets up the Laika configuration for API links, based on a map of package prefixes to scaladoc URLs provided by the plugin user. If none are provided, it will default to
tlSiteApiUrlif available.This allows links to the API docs to be easily added to Typelevel microsites, eg.:
@:api(cats.data.Chain)This implementation is based on the review comments for #225 and will supercede that PR.