Add Laika API link configuration #462
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -23,6 +23,8 @@ import laika.helium.config.Favicon | |
| import laika.helium.config.HeliumIcon | ||
| import laika.helium.config.IconLink | ||
| import laika.helium.config.ImageLink | ||
| import laika.rewrite.link.ApiLinks | ||
| import laika.rewrite.link.LinkConfig | ||
| import laika.sbt.LaikaPlugin | ||
| import laika.theme.ThemeProvider | ||
| import mdoc.MdocPlugin | ||
|
|
@@ -45,6 +47,8 @@ object TypelevelSitePlugin extends AutoPlugin { | |
| lazy val tlSiteHeliumConfig = settingKey[Helium]("The Typelevel Helium configuration") | ||
| lazy val tlSiteHeliumExtensions = | ||
| settingKey[ThemeProvider]("The Typelevel Helium extensions") | ||
| lazy val tlSiteApiLinks = | ||
| settingKey[Map[String, URL]]("URLs to API doc roots, by package prefix") | ||
| lazy val tlSiteApiUrl = settingKey[Option[URL]]("URL to the API docs") | ||
| lazy val tlSiteApiModule = | ||
| settingKey[Option[ModuleID]]("The module that publishes API docs") | ||
|
|
@@ -85,6 +89,7 @@ object TypelevelSitePlugin extends AutoPlugin { | |
| override def buildSettings = Seq( | ||
| tlSitePublishBranch := Some("main"), | ||
| tlSitePublishTags := tlSitePublishBranch.value.isEmpty, | ||
| tlSiteApiLinks := tlSiteApiUrl.value.map("*" -> _).toMap, | ||
| tlSiteApiUrl := None, | ||
| tlSiteApiPackage := None, | ||
| tlSiteRelatedProjects := Seq(TypelevelProject.Cats), | ||
|
|
@@ -106,6 +111,12 @@ object TypelevelSitePlugin extends AutoPlugin { | |
| .value: @nowarn("cat=other-pure-statement"), | ||
| tlSitePreview := previewTask.value, | ||
| Laika / sourceDirectories := Seq(mdocOut.value), | ||
| laikaConfig := laikaConfig | ||
| .value | ||
| .withConfigValue(LinkConfig(apiLinks = tlSiteApiLinks.value.toList.map { | ||
| case (packagePrefix, baseUri) => | ||
| ApiLinks(packagePrefix = packagePrefix, baseUri = baseUri.toString) | ||
| })), | ||
|
Comment on lines
+116
to
+119
There was a problem hiding this comment. Does the order here matter? e.g. what happens if the There was a problem hiding this comment. Order doesn't matter, Laika uses longest prefix match. |
||
| laikaTheme := tlSiteHeliumConfig.value.build.extend(tlSiteHeliumExtensions.value), | ||
| mdocVariables := { | ||
| mdocVariables.value ++ | ||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Unfortunately the
tlSiteApiUrlis not the "base" URL for the API. See (1) in #225 (comment).So maybe we need to add a
tlSiteApiBaseUrlor something ...There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's too bad,
tlSiteApiUrlworked fine for Cats. Is there a reasonable situation where stripping off everything after the last/wouldn't work? Or only defaulting totlSiteApiUrlif it ends in/?If
tlSiteApiBaseUrlwould only be used fortlSiteApiLinks, we may as well just have users populatetlSiteApiLinksthemselves 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.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, so for example http4s-dom sets its
tlSiteApiUrlto this, so it "zooms" to the right package.So I don't think it would work there.
tlSiteApiBaseUrlcan be used to maketlSiteApiUrland in many cases it will be auto-populated by the unidocs plugin.tlSiteApiUrlwasn't the right primitive.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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
…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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Right, but what happens if my project is
org.http4s.domand sbt-typelevel had pre-loadedorg.http4sAPI docs for me. It just doesn't work in general.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
uhh; right