docs: configure links in ScalaDoc; run link validator (#602)

.github/workflows/link-validator.yml

@@ -0,0 +1,46 @@
+name: Link Validator
+
+on:
+  workflow_dispatch:
+  pull_request:
+  schedule:
+    - cron:  '0 6 * * 1'
+
+permissions:
+  contents: read
+
+jobs:
+  validate-links:
+    runs-on: ubuntu-22.04
+    if: github.repository == 'akka/akka-persistence-r2dbc'
+    steps:
+      - name: Checkout
+        # https://github.com/actions/checkout/releases
+        # v4.1.1
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+        with:
+          # See https://github.com/actions/checkout/issues/299#issuecomment-677674415
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 100
+
+      - name: Fetch tags
+        run: git fetch --depth=100 origin +refs/tags/*:refs/tags/*
+
+      - name: Cache Coursier cache
+        # https://github.com/coursier/cache-action/releases
+        # v6.4.5
+        uses: coursier/cache-action@1ff273bff02a8787bc9f1877d347948af647956d
+
+      - name: Set up JDK 17
+        # https://github.com/coursier/setup-action/releases
+        # v1.3.5
+        uses: coursier/setup-action@7bde40eee928896f074dbb76d22dd772eed5c65f
+        with:
+          jvm: temurin:1.17.0.5
+          apps: cs
+
+      - name: sbt site
+        run: sbt docs/makeSite
+
+      - name: Run Link Validator
+        run: cs launch net.runne::site-link-validator:0.2.5 -- scripts/link-validator.conf

.github/workflows/publish.yml

@@ -62,7 +62,7 @@ jobs:
         # v1.3.5
         uses: coursier/setup-action@7bde40eee928896f074dbb76d22dd772eed5c65f
         with:
-          jvm: temurin:1.11
+          jvm: temurin:1.17
 
       - name: Publish
         run: |-

build.sbt

@@ -66,6 +66,18 @@ def common: Seq[Setting[_]] =
       "-Xms1G" :: "-Xmx1G" :: "-XX:MaxDirectMemorySize=256M" :: akkaProperties
     },
     projectInfoVersion := (if (isSnapshot.value) "snapshot" else version.value),
+    Compile / doc / scalacOptions := scalacOptions.value ++ Seq(
+      "-doc-title",
+      "Akka Persistence R2DBC",
+      "-doc-version",
+      version.value) ++ {
+      // make use of https://github.com/scala/scala/pull/8663
+      if (scalaBinaryVersion.value.startsWith("3")) {
+        Seq(s"-external-mappings:https://docs.oracle.com/en/java/javase/${Dependencies.JavaDocLinkVersion}/docs/api")
+      } else {
+        Seq("-jdk-api-doc-base", s"https://docs.oracle.com/en/java/javase/${Dependencies.JavaDocLinkVersion}/docs/api")
+      }
+    },
     Global / excludeLintKeys += projectInfoVersion,
     Global / excludeLintKeys += mimaReportSignatureProblems,
     Global / excludeLintKeys += mimaPreviousArtifacts,
@@ -152,7 +164,7 @@ lazy val docs = project
       "extref.akka.base_url" -> s"https://doc.akka.io/libraries/akka-core/${Dependencies.AkkaVersionInDocs}/%s",
       "extref.akka-docs.base_url" -> s"https://doc.akka.io/libraries/akka-core/${Dependencies.AkkaVersionInDocs}/%s",
       "extref.akka-projection.base_url" -> s"https://doc.akka.io/libraries/akka-projection/${Dependencies.AkkaProjectionVersionInDocs}/%s",
-      "extref.java-docs.base_url" -> "https://docs.oracle.com/en/java/javase/11/%s",
+      "extref.java-docs.base_url" -> s"https://docs.oracle.com/en/java/javase/${Dependencies.JavaDocLinkVersion}/%s",
       "scaladoc.scala.base_url" -> s"https://www.scala-lang.org/api/current/",
       "scaladoc.akka.persistence.r2dbc.base_url" -> s"/${(Preprocess / siteSubdirName).value}/",
       "javadoc.akka.persistence.r2dbc.base_url" -> "", // no Javadoc is published

project/Dependencies.scala

@@ -17,6 +17,9 @@ object Dependencies {
   val R2dbcH2Version = "1.0.0.RELEASE"
   val SqlServerR2dbcVersion = "1.0.2.RELEASE"
   val SqlServerJdbcVersion = "7.4.1.jre8"
+  // Java Platform version for JavaDoc creation
+  // sync with Java version in .github/workflows/release.yml#documentation
+  val JavaDocLinkVersion = 17
 
   object Compile {
     val akkaActorTyped = "com.typesafe.akka" %% "akka-actor-typed" % AkkaVersion

project/project-info.conf

@@ -15,10 +15,6 @@ project-info {
         text: "Lightbend Discuss"
         url: "https://discuss.lightbend.com/c/akka/"
       }
-      {
-        text: "akka/akka Gitter channel"
-        url: "https://gitter.im/akka/akka"
-      }
     ]
   }
   core: ${project-info.shared-info} {

scripts/link-validator.conf

@@ -0,0 +1,36 @@
+// config for https://github.com/ennru/site-link-validator/
+site-link-validator {
+  root-dir = "./docs/target/site/"
+  # relative to `root-dir`
+  start-file = "libraries/akka-persistence-r2dbc/snapshot/index.html"
+
+  # Resolves URLs with the given prefix as local files instead
+  link-mappings = [
+    {
+      prefix = "https://doc.akka.io/libraries/akka-persistence-r2dbc/snapshot/"
+      replace = "/libraries/akka-persistence-r2dbc/snapshot/"
+    }
+    {
+      prefix = "https://doc.akka.io/api/akka-persistence-r2dbc/snapshot/"
+      replace = "/api/akka-persistence-r2dbc/snapshot/"
+    }
+  ]
+
+  ignore-missing-local-files-regex = ""
+
+  ignore-files = []
+
+  ignore-prefixes = [
+    # GitHub will block with "429 Too Many Requests"
+    "https://github.com/akka/akka-persistence-r2dbc/"
+    # MVN repository forbids access after a few requests
+    "https://mvnrepository.com/artifact/",
+    "https://repo.akka.io/",
+    # created in api/akka-persistence-r2dbc/snapshot/akka/persistence/r2dbc/internal/Sql$.html
+    "https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/String$.html"
+  ]
+
+  non-https-whitelist = [
+//    "http://logback.qos.ch/"
+  ]
+}