Merge pull request #119 from armanbilge/feature/unidoc-artifact

Create `TypelevelUnidocPlugin`

Author: armanbilge

.github/workflows/ci.yml

@@ -86,11 +86,11 @@ jobs:
 
       - name: Make target directories
         if: github.event_name != 'pull_request' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/series/0.4')
-        run: mkdir -p github/target github-actions/target kernel/target versioning/target ci-release/target target .js/target mdocs/target site/target ci-signing/target mergify/target mima/target .jvm/target .native/target no-publish/target sonatype/target ci/target sonatype-ci-release/target core/target settings/target project/target
+        run: mkdir -p github/target github-actions/target kernel/target versioning/target ci-release/target target .js/target mdocs/target site/target ci-signing/target mergify/target unidoc/target mima/target .jvm/target .native/target no-publish/target sonatype/target ci/target sonatype-ci-release/target core/target settings/target project/target
 
       - name: Compress target directories
         if: github.event_name != 'pull_request' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/series/0.4')
-        run: tar cf targets.tar github/target github-actions/target kernel/target versioning/target ci-release/target target .js/target mdocs/target site/target ci-signing/target mergify/target mima/target .jvm/target .native/target no-publish/target sonatype/target ci/target sonatype-ci-release/target core/target settings/target project/target
+        run: tar cf targets.tar github/target github-actions/target kernel/target versioning/target ci-release/target target .js/target mdocs/target site/target ci-signing/target mergify/target unidoc/target mima/target .jvm/target .native/target no-publish/target sonatype/target ci/target sonatype-ci-release/target core/target settings/target project/target
 
       - name: Upload target directories
         if: github.event_name != 'pull_request' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/series/0.4')

.mergify.yml

@@ -144,6 +144,14 @@ pull_request_rules:
       add:
       - sonatype-ci-release
       remove: []
+- name: Label unidoc PRs
+  conditions:
+  - files~=^unidoc/
+  actions:
+    label:
+      add:
+      - unidoc
+      remove: []
 - name: Label versioning PRs
   conditions:
   - files~=^versioning/

build.sbt

@@ -31,6 +31,7 @@ lazy val root = tlCrossRootProject.aggregate(
   core,
   ciRelease,
   site,
+  unidoc,
   docs
 )
 
@@ -163,11 +164,19 @@ lazy val site = project
   )
   .dependsOn(kernel, github, githubActions, noPublish)
 
+lazy val unidoc = project
+  .in(file("unidoc"))
+  .enablePlugins(TypelevelUnidocPlugin)
+  .settings(
+    name := "sbt-typelevel-docs"
+  )
+
 lazy val docs = project
   .in(file("mdocs"))
   .enablePlugins(TypelevelSitePlugin)
   .settings(
     laikaConfig ~= { _.withRawContent },
+    tlSiteApiPackage := Some("org.typelevel.sbt"),
     tlSiteRelatedProjects := Seq(
       "sbt" -> url("https://www.scala-sbt.org/"),
       "sbt-crossproject" -> url("https://github.com/portable-scala/sbt-crossproject"),

site/src/main/scala/org/typelevel/sbt/TypelevelSitePlugin.scala

@@ -45,6 +45,10 @@ object TypelevelSitePlugin extends AutoPlugin {
     lazy val tlSiteHeliumExtensions =
       settingKey[ThemeProvider]("The Typelevel Helium extensions")
     lazy val tlSiteApiUrl = settingKey[Option[URL]]("URL to the API docs")
+    lazy val tlSiteApiModule =
+      settingKey[Option[ModuleID]]("The module that publishes API docs")
+    lazy val tlSiteApiPackage = settingKey[Option[String]](
+      "The top-level package for your API docs (e.g. org.typlevel.sbt)")
     lazy val tlSiteRelatedProjects =
       settingKey[Seq[(String, URL)]]("A list of related projects (default: cats)")
 
@@ -73,10 +77,15 @@ object TypelevelSitePlugin extends AutoPlugin {
   override def requires =
     MdocPlugin && LaikaPlugin && TypelevelGitHubPlugin && GenerativePlugin && NoPublishPlugin
 
+  override def globalSettings = Seq(
+    tlSiteApiModule := None
+  )
+
   override def buildSettings = Seq(
     tlSitePublishBranch := Some("main"),
     tlSitePublishTags := tlSitePublishBranch.value.isEmpty,
     tlSiteApiUrl := None,
+    tlSiteApiPackage := None,
     tlSiteRelatedProjects := Seq(TypelevelProject.Cats),
     tlSiteKeepFiles := true,
     homepage := {
@@ -98,17 +107,32 @@ object TypelevelSitePlugin extends AutoPlugin {
     Laika / sourceDirectories := Seq(mdocOut.value),
     laikaTheme := tlSiteHeliumConfig.value.build.extend(tlSiteHeliumExtensions.value),
     mdocVariables ++= Map(
-      "VERSION" -> GitHelper
-        .previousReleases(fromHead = true)
-        .filterNot(_.isPrerelease)
-        .headOption
-        .fold(version.value)(_.toString),
+      "VERSION" -> currentRelease.value.getOrElse(version.value),
       "SNAPSHOT_VERSION" -> version.value
     ),
     tlSiteHeliumExtensions := TypelevelHeliumExtensions(
       licenses.value.headOption,
       tlSiteRelatedProjects.value
     ),
+    tlSiteApiUrl := {
+      val javadocioUrl = for {
+        moduleId <- (ThisProject / tlSiteApiModule).value
+        cross <- CrossVersion(
+          moduleId.crossVersion,
+          scalaVersion.value,
+          scalaBinaryVersion.value
+        )
+        version <- currentRelease.value
+      } yield {
+        val o = moduleId.organization
+        val n = cross(moduleId.name)
+        val v = version
+        val p = tlSiteApiPackage.value.fold("")(_.replace('.', '/') + '/')
+        url(s"https://www.javadoc.io/doc/$o/$n/$v/$p")
+      }
+
+      tlSiteApiUrl.value.orElse(javadocioUrl)
+    },
     tlSiteHeliumConfig := {
       Helium
         .defaults
@@ -218,6 +242,14 @@ object TypelevelSitePlugin extends AutoPlugin {
       )
   )
 
+  private lazy val currentRelease = Def.setting {
+    GitHelper
+      .previousReleases(fromHead = true)
+      .filterNot(_.isPrerelease)
+      .headOption
+      .map(_.toString)
+  }
+
   private def previewTask = Def
     .taskDyn {
       // inlined from https://github.com/planet42/Laika/blob/9022f6f37c9017f7612fa59398f246c8e8c42c3e/sbt/src/main/scala/laika/sbt/Tasks.scala#L192

sonatype/build.sbt

@@ -1,2 +1,3 @@
 addSbtPlugin("com.typesafe" % "sbt-mima-plugin" % "1.0.1")
 addSbtPlugin("org.xerial.sbt" % "sbt-sonatype" % "3.9.11")
+addSbtPlugin("com.github.sbt" % "sbt-unidoc" % "0.5.0")

sonatype/src/main/scala/org/typelevel/sbt/TypelevelSonatypePlugin.scala

@@ -62,24 +62,23 @@ object TypelevelSonatypePlugin extends AutoPlugin {
           "s01.oss.sonatype.org"
       }
     },
-    apiURL := {
-      val javadocio =
-        if (isSnapshot.value || sbtPlugin.value || !publishArtifact.value)
-          None // javadoc.io doesn't support snapshots, sbt plugins, or unpublished modules ;)
-        else
-          CrossVersion(
-            crossVersion.value,
-            scalaVersion.value,
-            scalaBinaryVersion.value
-          ).map { cross =>
-            url(
-              s"https://www.javadoc.io/doc/${organization.value}/${cross(moduleName.value)}/${version.value}/")
-          }
-
-      apiURL.value.orElse(javadocio)
-    }
+    apiURL := apiURL.value.orElse(javadocioUrl.value)
   )
 
+  private[sbt] def javadocioUrl = Def.setting {
+    if (isSnapshot.value || sbtPlugin.value || !publishArtifact.value)
+      None // javadoc.io doesn't support snapshots, sbt plugins, or unpublished modules ;)
+    else
+      CrossVersion(
+        crossVersion.value,
+        scalaVersion.value,
+        scalaBinaryVersion.value
+      ).map { cross =>
+        url(
+          s"https://www.javadoc.io/doc/${organization.value}/${cross(moduleName.value)}/${version.value}/")
+      }
+  }
+
   private def sonatypeBundleReleaseIfRelevant: Command =
     Command.command("tlSonatypeBundleReleaseIfRelevant") { state =>
       if (state.getSetting(isSnapshot).getOrElse(false))

sonatype/src/main/scala/org/typelevel/sbt/TypelevelUnidocPlugin.scala

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2022 Typelevel
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.typelevel.sbt
+
+import sbt._, Keys._
+import com.typesafe.tools.mima.plugin.MimaPlugin.autoImport._
+import sbtunidoc.ScalaUnidocPlugin
+
+object TypelevelUnidocPlugin extends AutoPlugin {
+
+  override def requires = ScalaUnidocPlugin
+
+  override def trigger = noTrigger
+
+  import ScalaUnidocPlugin.autoImport._
+  import TypelevelSonatypePlugin.javadocioUrl
+
+  override def projectSettings = Seq(
+    Compile / packageDoc / mappings := (ScalaUnidoc / packageDoc / mappings).value,
+    ThisBuild / apiURL := javadocioUrl.value,
+    mimaPreviousArtifacts := Set.empty,
+    // tell the site plugin about us, without forcing the dependency!
+    ThisBuild / SettingKey[Option[ModuleID]]("tlSiteApiModule") := Some(projectID.value)
+  )
+
+}