docs: revise URL structure (libraries) (#85)

* docs: revise URL structure (libraries)

* scalafmtSbt

* Cross link to Java 17 APIs

* JPMS links

.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.event.repository.fork == false
+    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

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

build.sbt

@@ -10,7 +10,7 @@ inThisBuild(
   Seq(
     organization := "com.lightbend.akka",
     organizationName := "Lightbend Inc.",
-    homepage := Some(url("https://doc.akka.io/docs/akka-persistence-dynamodb/current")),
+    homepage := Some(url("https://doc.akka.io/libraries/akka-persistence-dynamodb/current")),
     scmInfo := Some(
       ScmInfo(
         url("https://github.com/akka/akka-persistence-dynamodb"),
@@ -19,13 +19,18 @@ inThisBuild(
     developers += Developer(
       "contributors",
       "Contributors",
-      "https://gitter.im/akka/dev",
+      "",
       url("https://github.com/akka/akka-persistence-dynamodb/graphs/contributors")),
     releaseNotesURL := (
       if (isSnapshot.value) None
       else Some(url(s"https://github.com/akka/akka-persistence-dynamodb/releases/tag/v${version.value}"))
     ),
-    licenses := Seq(("BUSL-1.1", url("https://raw.githubusercontent.com/akka/akka-persistence-dynamodb/main/LICENSE"))),
+    licenses := {
+      val tagOrBranch =
+        if (isSnapshot.value) "main"
+        else "v" + version.value
+      Seq(("BUSL-1.1", url(s"https://github.com/akka/akka-persistence-dynamodb/blob/${tagOrBranch}/LICENSE")))
+    },
     description := "An Akka Persistence plugin backed by Amazon DynamoDB",
     // append -SNAPSHOT to version when isSnapshot
     dynverSonatypeSnapshots := true,
@@ -53,7 +58,20 @@ def common: Seq[Setting[_]] =
     }),
     Compile / console / scalacOptions := defaultScalacOptions,
     Test / console / scalacOptions := defaultScalacOptions,
-    Compile / doc / scalacOptions := defaultScalacOptions,
+    Compile / doc / scalacOptions := defaultScalacOptions ++ Seq(
+      "-doc-title",
+      "Akka Persistence DynamoDB",
+      "-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/java.base/")
+      } else
+        Seq(
+          "-jdk-api-doc-base",
+          s"https://docs.oracle.com/en/java/javase/${Dependencies.JavaDocLinkVersion}/docs/api/java.base/")
+    },
     Compile / doc / autoAPIMappings := true,
     headerLicense := Some(HeaderLicense.Custom("""Copyright (C) 2024 Lightbend Inc. <https://www.lightbend.com>""")),
     Test / logBuffered := false,
@@ -128,24 +146,24 @@ lazy val docs = project
     previewPath := (Paradox / siteSubdirName).value,
     Preprocess / siteSubdirName := s"api/akka-persistence-dynamodb/${projectInfoVersion.value}",
     Preprocess / sourceDirectory := (LocalRootProject / ScalaUnidoc / unidoc / target).value,
-    Paradox / siteSubdirName := s"docs/akka-persistence-dynamodb/${projectInfoVersion.value}",
+    Paradox / siteSubdirName := s"libraries/akka-persistence-dynamodb/${projectInfoVersion.value}",
     paradoxGroups := Map("Language" -> Seq("Java", "Scala")),
     Compile / paradoxProperties ++= Map(
-      "project.url" -> "https://doc.akka.io/docs/akka-persistence-dynamodb/current/",
-      "canonical.base_url" -> "https://doc.akka.io/docs/akka-persistence-dynamodb/current",
+      "project.url" -> "https://doc.akka.io/libraries/akka-persistence-dynamodb/current/",
+      "canonical.base_url" -> "https://doc.akka.io/libraries/akka-persistence-dynamodb/current",
       "akka.version" -> Dependencies.AkkaVersion,
       "scala.version" -> scalaVersion.value,
       "scala.binary.version" -> scalaBinaryVersion.value,
-      "extref.akka.base_url" -> s"https://doc.akka.io/docs/akka/${Dependencies.AkkaVersionInDocs}/%s",
-      "extref.akka-docs.base_url" -> s"https://doc.akka.io/docs/akka/${Dependencies.AkkaVersionInDocs}/%s",
-      "extref.akka-projection.base_url" -> s"https://doc.akka.io/docs/akka-projection/${Dependencies.AkkaProjectionVersionInDocs}/%s",
+      "extref.akka-core.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",
+      "scaladoc.com.typesafe.config.base_url" -> s"https://lightbend.github.io/config/latest/api/",
       "scaladoc.scala.base_url" -> s"https://www.scala-lang.org/api/current/",
       "scaladoc.akka.persistence.dynamodb.base_url" -> s"/${(Preprocess / siteSubdirName).value}/",
+      "scaladoc.akka.projection.base_url" -> s"https://doc.akka.io/api/akka-projection/${Dependencies.AkkaProjectionVersionInDocs}/",
+      "scaladoc.akka.base_url" -> s"https://doc.akka.io/api/akka-core/${Dependencies.AkkaVersionInDocs}/",
       "javadoc.akka.persistence.dynamodb.base_url" -> "", // no Javadoc is published
-      "scaladoc.akka.base_url" -> s"https://doc.akka.io/api/akka/${Dependencies.AkkaVersionInDocs}/",
-      "javadoc.akka.base_url" -> s"https://doc.akka.io/japi/akka/${Dependencies.AkkaVersionInDocs}/",
-      "scaladoc.com.typesafe.config.base_url" -> s"https://lightbend.github.io/config/latest/api/"),
+      "javadoc.akka.base_url" -> s"https://doc.akka.io/japi/akka-core/${Dependencies.AkkaVersionInDocs}/"),
     ApidocPlugin.autoImport.apidocRootPackage := "akka",
     apidocRootPackage := "akka",
     resolvers += Resolver.jcenterRepo,

docs/src/main/paradox/cleanup.md

@@ -8,7 +8,7 @@ snapshot](query.md#eventsbyslicesstartingfromsnapshots), and then events can be
 
 In some cases keeping all events is not possible, or data must be removed for regulatory reasons, such as compliance
 with GDPR. `EventSourcedBehavior`s can also automatically
-@extref:[delete events on snapshot](akka:typed/persistence-snapshot.html#event-deletion). Snapshotting is useful even
+@extref:[delete events on snapshot](akka-core:typed/persistence-snapshot.html#event-deletion). Snapshotting is useful even
 if events aren't deleted as it speeds up recovery.
 
 Deleting all events immediately when an entity has reached its terminal deleted state would have the consequence that

docs/src/main/paradox/journal.md

@@ -1,7 +1,7 @@
 # Journal plugin
 
 The journal plugin enables storing and loading events for
-@extref:[event sourced persistent actors](akka:typed/persistence.html).
+@extref:[event sourced persistent actors](akka-core:typed/persistence.html).
 
 ## Tables
 
@@ -64,14 +64,14 @@ The following can be overridden in your `application.conf` for the journal speci
 
 ## Event serialization
 
-The events are serialized with @extref:[Akka Serialization](akka:serialization.html) and the binary representation
+The events are serialized with @extref:[Akka Serialization](akka-core:serialization.html) and the binary representation
 is stored in the `event_payload` column together with information about what serializer that was used in the
 `event_ser_id` and `event_ser_manifest` columns.
 
 ## Retryable errors
 
 When persisting events, any DynamoDB errors that are considered retryable, such as when provisioned throughput capacity
-is exceeded, will cause events to be @extref:[rejected](akka:typed/persistence.html#journal-rejections) rather than
+is exceeded, will cause events to be @extref:[rejected](akka-core:typed/persistence.html#journal-rejections) rather than
 marked as a journal failure. A supervision strategy for `EventRejectedException` failures can then be added to
 EventSourcedBehaviors, so that entities can be resumed on these retryable errors rather than stopped or restarted.
 
@@ -99,7 +99,7 @@ The TTL attribute to use for the journal or snapshot tables is named `expiry`.
 Time-to-live settings are configured per entity type. The entity type can also be matched by prefix by using a `*` at
 the end of the key.
 
-If events are being @extref:[deleted on snapshot](akka:typed/persistence-snapshot.html#event-deletion), the journal can
+If events are being @extref:[deleted on snapshot](akka-core:typed/persistence-snapshot.html#event-deletion), the journal can
 be configured to instead set an expiry time for the deleted events, given a time-to-live duration to use. For example,
 deleted events can be configured to expire in 7 days, rather than being deleted immediately, for a particular entity
 type:

docs/src/main/paradox/projection.md

@@ -112,7 +112,7 @@ Scala
 The @ref:[`ShoppingCartTransactHandler` is shown below](#transact-handler).
 
 It is possible to dynamically scale the number of Projection instances as described in the @extref:[Sharded Daemon
-Process documentation](akka:typed/cluster-sharded-daemon-process.html#dynamic-scaling-of-number-of-workers).
+Process documentation](akka-core:typed/cluster-sharded-daemon-process.html#dynamic-scaling-of-number-of-workers).
 
 There are alternative ways of running the `ProjectionBehavior` as described in @extref:[Running a Projection](akka-projection:running.html).
 
@@ -291,7 +291,7 @@ instance.
 ### Actor handler
 
 A good alternative for advanced state management is to implement the handler as an
-@extref:[actor](akka:typed/typed/actors.html) which is described in
+@extref:[actor](akka-core:typed/typed/actors.html) which is described in
 @extref:[Processing with Actor](akka-projection:actor.html).
 
 ### Flow handler

docs/src/main/paradox/query.md

@@ -2,7 +2,7 @@
 
 ## Event sourced queries
 
-@apidoc[DynamoDBReadJournal] implements the following @extref:[Persistence Queries](akka:persistence-query.html):
+@apidoc[DynamoDBReadJournal] implements the following @extref:[Persistence Queries](akka-core:persistence-query.html):
 
 * `eventsBySlices`, `currentEventsBySlices`
 

docs/src/main/paradox/snapshots.md

@@ -1,7 +1,7 @@
 # Snapshot store plugin
 
 The snapshot plugin enables storing and loading snapshots for
-@extref:[event sourced persistent actors](akka:typed/persistence.html).
+@extref:[event sourced persistent actors](akka-core:typed/persistence.html).
 
 ## Tables
 
@@ -69,11 +69,11 @@ The following can be overridden in your `application.conf` for the snapshot spec
 ## Usage
 
 The snapshot plugin is used whenever a snapshot write is triggered through the
-@extref:[Akka Persistence APIs](akka:typed/persistence-snapshot.html).
+@extref:[Akka Persistence APIs](akka-core:typed/persistence-snapshot.html).
 
 ## Snapshot serialization
 
-The state is serialized with @extref:[Akka Serialization](akka:serialization.html) and the binary snapshot representation
+The state is serialized with @extref:[Akka Serialization](akka-core:serialization.html) and the binary snapshot representation
 is stored in the `snapshot` column together with information about what serializer that was used in the
 `ser_id` and `ser_manifest` columns.
 

project/Dependencies.scala

@@ -12,8 +12,13 @@ object Dependencies {
   val AkkaVersion = System.getProperty("override.akka.version", "2.9.5")
   val AkkaVersionInDocs = VersionNumber(AkkaVersion).numbers match { case Seq(major, minor, _*) => s"$major.$minor" }
   val AkkaProjectionVersion = "1.5.4"
-  val AkkaProjectionVersionInDocs = "current"
+  val AkkaProjectionVersionInDocs = VersionNumber(AkkaProjectionVersion).numbers match {
+    case Seq(major, minor, _*) => s"$major.$minor"
+  }
   val AwsSdkVersion = "2.25.59"
+  // Java Platform version for JavaDoc creation
+  // sync with Java version in .github/workflows/publish.yml#documentation
+  val JavaDocLinkVersion = 17
 
   object Compile {
     val akkaActorTyped = "com.typesafe.akka" %% "akka-actor-typed" % AkkaVersion

project/project-info.conf

@@ -12,12 +12,8 @@ project-info {
     }
     forums: [
       {
-        text: "Lightbend Discuss"
-        url: "https://discuss.lightbend.com/c/akka/"
-      }
-      {
-        text: "akka/akka Gitter channel"
-        url: "https://gitter.im/akka/akka"
+        text: "Akka Discuss"
+        url: "https://discuss.akka.io/c/akka/"
       }
     ]
   }

scripts/link-validator.conf

@@ -0,0 +1,33 @@
+// 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-dynamodb/snapshot/index.html"
+
+  # Resolves URLs with the given prefix as local files instead
+  link-mappings = [
+    {
+      prefix = "https://doc.akka.io/libraries/akka-persistence-dynamodb/snapshot/"
+      replace = "/libraries/akka-persistence-dynamodb/snapshot/"
+    }
+    {
+      prefix = "https://doc.akka.io/api/akka-persistence-dynamodb/snapshot/"
+      replace = "/api/akka-persistence-dynamodb/snapshot/"
+    }
+  ]
+
+  ignore-missing-local-files-regex = ""
+
+  ignore-files = []
+
+  ignore-prefixes = [
+    # GitHub will block with "429 Too Many Requests"
+    "https://github.com/akka/akka-persistence-dynamodb/"
+    # MVN repository forbids access after a few requests
+    "https://mvnrepository.com/artifact/",
+    "https://repo.akka.io/",
+  ]
+
+  non-https-whitelist = [
+  ]
+}