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

.github/workflows/check-build-test.yml

@@ -45,43 +45,6 @@ jobs:
       - name: "Code style, compile tests"
         run: sbt "verifyCodeStyle; +Test/compile"
 
-
-  documentation:
-    name: ScalaDoc, Documentation with Paradox
-    if: github.event.repository.fork == false
-    runs-on: ubuntu-22.04
-    env:
-      JAVA_OPTS: -Xms2G -Xmx2G -Xss2M -XX:ReservedCodeCacheSize=256M -Dfile.encoding=UTF-8
-
-    steps:
-      - name: Checkout
-        # https://github.com/actions/checkout/releases
-        # v4.1.1
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
-        with: # https://github.com/olafurpg/setup-scala#faster-checkout-of-big-repos
-          fetch-depth: 100
-
-      - name: Fetch tags
-        run: git fetch --depth=100 origin +refs/tags/*:refs/tags/*
-
-      - name: Set up JDK 11
-        # https://github.com/coursier/setup-action/releases
-        # v1.3.5
-        uses: coursier/setup-action@7bde40eee928896f074dbb76d22dd772eed5c65f
-        with:
-          jvm: temurin:1.11
-
-      - name: Cache Coursier cache
-        # https://github.com/coursier/cache-action/releases
-        # v6.4.5
-        uses: coursier/cache-action@1ff273bff02a8787bc9f1877d347948af647956d
-
-      - name: "Create all API docs and create site with Paradox"
-        run: sbt "unidoc; docs/makeSite"
-
-      - name: Run Link Validator
-        run: cs launch net.runne::site-link-validator:0.2.3 -- project/link-validator.conf
-
   test:
     name: Test
     if: github.event.repository.fork == false

.github/workflows/link-validator.yml

@@ -0,0 +1,48 @@
+name: Link Validator
+
+on:
+  workflow_dispatch:
+  pull_request:
+  schedule:
+    - cron:  '0 5 1 * *'
+
+permissions:
+  contents: read
+
+jobs:
+  documentation:
+    name: ScalaDoc, Documentation with Paradox
+    if: github.event.repository.fork == false
+    runs-on: ubuntu-22.04
+    env:
+      JAVA_OPTS: -Xms2G -Xmx2G -Xss2M -XX:ReservedCodeCacheSize=256M -Dfile.encoding=UTF-8
+
+    steps:
+      - name: Checkout
+        # https://github.com/actions/checkout/releases
+        # v4.1.1
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+        with: # https://github.com/olafurpg/setup-scala#faster-checkout-of-big-repos
+          fetch-depth: 100
+
+      - name: Fetch tags
+        run: git fetch --depth=100 origin +refs/tags/*:refs/tags/*
+
+      - 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
+
+      - name: Cache Coursier cache
+        # https://github.com/coursier/cache-action/releases
+        # v6.4.5
+        uses: coursier/cache-action@1ff273bff02a8787bc9f1877d347948af647956d
+
+      - name: "Create all API docs and create site with Paradox"
+        run: sbt "unidoc; docs/makeSite"
+
+      - name: Run Link Validator
+        run: cs launch net.runne::site-link-validator:0.2.5 -- project/link-validator.conf
+

.github/workflows/publish.yml

@@ -61,12 +61,12 @@ jobs:
           # we don't know what commit the last tag was it's safer to get entire repo so previousStableVersion resolves
           fetch-depth: 0
 
-      - name: Set up JDK 11
+      - name: Set up JDK 17
         # https://github.com/coursier/setup-action/releases
         # v1.3.5
         uses: coursier/setup-action@7bde40eee928896f074dbb76d22dd772eed5c65f
         with:
-          jvm: temurin:1.11
+          jvm: temurin:1.17
 
       - name: Publish
         run: |-

README.md

@@ -3,16 +3,16 @@ Cassandra Plugins for Akka Persistence
 
 The Akka family of projects is managed by teams at [Lightbend](https://lightbend.com/) with help from the community.
 
-Replicated [Akka Persistence](https://doc.akka.io/docs/akka/current/scala/persistence.html) journal and snapshot store backed by [Apache Cassandra](https://cassandra.apache.org/).
+Replicated [Akka Persistence](https://doc.akka.io/libraries/akka-core/current/scala/persistence.html) journal and snapshot store backed by [Apache Cassandra](https://cassandra.apache.org/).
 
 For questions please use the [discuss.akka.io](https://discuss.lightbend.com/c/akka/).
 
 
 ## Documentation
 
-The current version's documentation is available at https://doc.akka.io/docs/akka-persistence-cassandra/current/.
+The current version's documentation is available at https://doc.akka.io/libraries/akka-persistence-cassandra/current/.
 
-[Snapshot documentation](https://doc.akka.io/docs/akka-persistence-cassandra/snapshot/) and snapshot artifacts at https://repo.akka.io/snapshots are published for every successful `main` branch build.
+[Snapshot documentation](https://doc.akka.io/libraries/akka-persistence-cassandra/snapshot/) and snapshot artifacts at https://repo.akka.io/snapshots are published for every successful `main` branch build.
 
 For versions earlier than 1.0.0, check this README.md file for the corresponding release tag.
 

build.sbt

@@ -75,21 +75,21 @@ lazy val docs = project
     previewPath := (Paradox / siteSubdirName).value,
     Preprocess / siteSubdirName := s"api/akka-persistence-cassandra/${projectInfoVersion.value}",
     Preprocess / sourceDirectory := (LocalRootProject / ScalaUnidoc / unidoc / target).value,
-    Paradox / siteSubdirName := s"docs/akka-persistence-cassandra/${projectInfoVersion.value}",
+    Paradox / siteSubdirName := s"libraries/akka-persistence-cassandra/${projectInfoVersion.value}",
     Compile / paradoxProperties ++= Map(
-        "project.url" -> "https://doc.akka.io/docs/akka-persistence-cassandra/current/",
-        "canonical.base_url" -> "https://doc.akka.io/docs/akka-persistence-cassandra/current",
+        "project.url" -> "https://doc.akka.io/libraries/akka-persistence-cassandra/current/",
+        "canonical.base_url" -> "https://doc.akka.io/libraries/akka-persistence-cassandra/current",
         "akka.version" -> Dependencies.AkkaVersion,
         // Akka
-        "extref.akka.base_url" -> s"https://doc.akka.io/docs/akka/${Dependencies.AkkaVersionInDocs}/%s",
+        "extref.akka.base_url" -> s"https://doc.akka.io/libraries/akka-core/${Dependencies.AkkaVersionInDocs}/%s",
         "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}/",
         // Alpakka
         "extref.alpakka.base_url" -> s"https://doc.akka.io/docs/alpakka/${Dependencies.AlpakkaVersionInDocs}/%s",
         "scaladoc.akka.stream.alpakka.base_url" -> s"https://doc.akka.io/api/alpakka/${Dependencies.AlpakkaVersionInDocs}/",
         "javadoc.akka.stream.alpakka.base_url" -> "",
         // APC 0.x
-        "extref.apc-0.x.base_url" -> s"https://doc.akka.io/docs/akka-persistence-cassandra/0.103/%s",
+        "extref.apc-0.x.base_url" -> s"https://doc.akka.io/libraries/akka-persistence-cassandra/0.103/%s",
         // Cassandra
         "extref.cassandra.base_url" -> s"https://cassandra.apache.org/doc/${Dependencies.CassandraVersionInDocs}/%s",
         // Datastax Java driver

core/src/main/scala/akka/persistence/cassandra/EventsByTagMigration.scala

@@ -153,7 +153,7 @@ class EventsByTagMigration(
    * Migrates the entire `messages` table to the the new `tag_views` table.
    *
    * Before running this you must run the migration of the `all_persistence_ids`
-   * table as described in https://doc.akka.io/docs/akka-persistence-cassandra/current/migrations.html#all-persistenceIds-query
+   * table as described in https://doc.akka.io/libraries/akka-persistence-cassandra/current/migrations.html#all-persistenceIds-query
    *
    * Uses [CassandraReadJournal.currentPersistenceIds] to find all persistenceIds.
    * Note that this is a very inefficient cassandra query so might timeout. If so

docs/release-train-issue-template.md

@@ -25,7 +25,7 @@ Variables to be expanded in this template:
 ### Check availability
 
 - [ ] Check [API](https://doc.akka.io/api/akka-persistence-cassandra/$VERSION$/) documentation
-- [ ] Check [reference](https://doc.akka.io/docs/akka-persistence-cassandra/$VERSION$/) documentation. Check that the reference docs were deployed and show a version warning (see section below on how to fix the version warning).
+- [ ] Check [reference](https://doc.akka.io/libraries/akka-persistence-cassandra/$VERSION$/) documentation. Check that the reference docs were deployed and show a version warning (see section below on how to fix the version warning).
 - [ ] Check the release on https://repo.akka.io/maven/com/typesafe/akka/akka-persistence-cassandra_2.13/$VERSION$/akka-persistence-cassandra_2.13-$VERSION$.pom
 
 ### When everything is on https://repo.akka.io/maven
@@ -55,7 +55,7 @@ For minor or major releases:
 
 ### Afterwards
 
-- [ ] Update [akka-dependencies bom](https://github.com/lightbend/akka-dependencies) and version for [Akka module versions](https://doc.akka.io/docs/akka-dependencies/current/) in [akka-dependencies repo](https://github.com/akka/akka-dependencies)
+- [ ] Update [akka-dependencies bom](https://github.com/lightbend/akka-dependencies) and version for [Akka module versions](https://doc.akka.io/libraries/akka-dependencies/current/) in [akka-dependencies repo](https://github.com/akka/akka-dependencies)
 - [ ] Update [akka-dependencies bom](https://github.com/lightbend/akka-dependencies)
 - [ ] Update [Akka Guide samples](https://github.com/akka/akka-platform-guide)
 - Close this issue

docs/src/main/paradox/cleanup.md

@@ -1,9 +1,9 @@
 # Database Cleanup
 
-If possible, it is best to keep all events in an event sourced system. That way new [projections](https://doc.akka.io/docs/akka-projection/current/index.html) 
+If possible, it is best to keep all events in an event sourced system. That way new [projections](https://doc.akka.io/libraries/akka-projection/current/index.html) 
 and the `tag_view` table can be re-built if it is corrupted (e.g. due to a two persistence ids writing events from two nodes in a split brain).
 
-In some cases keeping all events is not possible. `EventSourcedBehavior`s can automatically snapshot state and delete events as described in the [Akka docs](https://doc.akka.io/docs/akka/current/typed/persistence-snapshot.html#snapshot-deletion).
+In some cases keeping all events is not possible. `EventSourcedBehavior`s can automatically snapshot state and delete events as described in the [Akka docs](https://doc.akka.io/libraries/akka-core/current/typed/persistence-snapshot.html#snapshot-deletion).
 Snapshotting is useful even if events aren't deleted as it speeds up recovery.
 
 The @apidoc[akka.persistence.cassandra.cleanup.Cleanup] tool can retrospectively clean up the journal. Its operations include:

docs/src/main/paradox/healthcheck.md

@@ -1,6 +1,6 @@
 # Health check
 
-A [health check for Akka Management](https://doc.akka.io/docs/akka-management/current/healthchecks.html)
+A [health check for Akka Management](https://doc.akka.io/libraries/akka-management/current/healthchecks.html)
 is provided. To enable it you need to add the following configuration
 
 ```

docs/src/main/paradox/journal.md

@@ -108,7 +108,7 @@ If a persistent actor for which this has happened is started in another datacent
 if it wasn't replicated.
 If the Cassandra data in the datacenter with the outage is recovered then the event that was not replicated will 
 eventually be replicated to all datacenters resulting in a duplicate sequence number.
-With the default [`replay-filter`](https://doc.akka.io/docs/akka/current/typed/persistence.html#replay-filter) the
+With the default [`replay-filter`](https://doc.akka.io/libraries/akka-core/current/typed/persistence.html#replay-filter) the
 duplicate event from the original datacenter will is discarded in subsequent replays of the persistent actor.
 
 Using `QUORUM` for multi datacenter setups increases latency and decreased availability as to reach `QUORUM` nodes in
@@ -128,7 +128,7 @@ datastax-java-driver.profiles {
 ## Event deletion and retention
 
 In applications with an Event Sourcing model of persistence, an idealized journal is _append-only_: events are never deleted.
-However, it is possible in Akka Persistence to use [snapshot-based retention](https://doc.akka.io/docs/akka/current/typed/persistence-snapshot.html#event-deletion),
+However, it is possible in Akka Persistence to use [snapshot-based retention](https://doc.akka.io/libraries/akka-core/current/typed/persistence-snapshot.html#event-deletion),
 and it is also possible to @ref[perform bulk deletions of events](./cleanup.md) in Akka Persistence Cassandra.  If using these
 features, it's important to be aware of [how deletion is performed in Cassandra](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlAboutDeletes.html).
 Specifically, deletion of events is actually inserting a tombstone telling Cassandra "this event is deleted".  In the presence

docs/src/main/paradox/migrations.md

@@ -246,7 +246,7 @@ CassandraLauncher.start(
 
 ## Migrations from 0.23 to 0.50
 
-The Persistence Query API changed slightly, see [migration guide for Akka 2.5](https://doc.akka.io/docs/akka/2.5/project/migration-guide-2.4.x-2.5.x.html#persistence-query).
+The Persistence Query API changed slightly, see [migration guide for Akka 2.5](https://doc.akka.io/libraries/akka-core/2.5/project/migration-guide-2.4.x-2.5.x.html#persistence-query).
 
 ## Migrations from 0.11 to 0.12
 

docs/src/main/paradox/overview.md

@@ -8,7 +8,7 @@ The Akka Persistence Cassandra plugin allows for using [Apache Cassandra](https:
 
 ## Dependencies
 
-This plugin requires **Akka $akka.version$** or later. See [Akka's Binary Compatibility Rules](https://doc.akka.io/docs/akka/current/common/binary-compatibility-rules.html) for details.
+This plugin requires **Akka $akka.version$** or later. See [Akka's Binary Compatibility Rules](https://doc.akka.io/libraries/akka-core/current/common/binary-compatibility-rules.html) for details.
 
 The Akka dependencies are available from Akka's library repository. To access them there, you need to configure the URL for this repository.
 
@@ -47,9 +47,9 @@ To use the plugin with **Akka 2.5.x** you must use @extref:[version 0.103](apc-0
 
 ## Supported features
 
-Be aware of that many of the new features of [Akka Distributed Cluster](https://doc.akka.io/docs/akka-distributed-cluster/current/)
-and [Akka Edge](https://doc.akka.io/docs/akka-edge/current/) are only implemented by the
-[Akka Persistence R2DBC plugin](https://doc.akka.io/docs/akka-persistence-r2dbc/current/) and are not supported by the
+Be aware of that many of the new features of [Akka Distributed Cluster](https://doc.akka.io/libraries/akka-distributed-cluster/current/)
+and [Akka Edge](https://doc.akka.io/libraries/akka-edge/current/) are only implemented by the
+[Akka Persistence R2DBC plugin](https://doc.akka.io/libraries/akka-persistence-r2dbc/current/) and are not supported by the
 Cassandra plugin.
 
 Those features were developed for Distributed Cluster and Edge, but they are also useful in other contexts.

docs/src/main/paradox/testing.md

@@ -3,7 +3,7 @@
 There are a number of options for testing persistent actors when using the Akka Persistence Cassandra plugin.
 The two main methods are:
 
-* Testing using the inmem journal as shown in the [Akka docs](https://doc.akka.io/docs/akka/current/typed/persistence-testing.html).
+* Testing using the inmem journal as shown in the [Akka docs](https://doc.akka.io/libraries/akka-core/current/typed/persistence-testing.html).
 * Testing against a real Cassandra instance.
 
 For testing against Cassandra you can:
@@ -27,4 +27,4 @@ For testing it can be convenient to enable automatic creation of keyspace and ta
     }
 
 
-Another recommended configuration is to not run test in parallel to avoid contention around manipulating the cassandra keyspace. Using sbt, you are able to control the `parallelExecution` as described [here](https://www.scala-sbt.org/1.x/docs/Testing.html).
+Another recommended configuration is to not run test in parallel to avoid contention around manipulating the cassandra keyspace. Using sbt, you are able to control the `parallelExecution` as described [here](https://www.scala-sbt.org/1.x/docs/Testing.html).

project/Common.scala

@@ -75,11 +75,17 @@ object Common extends AutoPlugin {
         "-doc-canonical-base-url",
         "https://doc.akka.io/api/akka-persistence-cassandra/current/")
       ++ {
+        // make use of https://github.com/scala/scala/pull/8663
         if (scalaBinaryVersion.value.startsWith("3")) {
-          Seq("-skip-packages:akka.pattern") // different usage in scala3
-        } else {
-          Seq("-skip-packages", "akka.pattern") // for some reason Scaladoc creates this
-        }
+          Seq(
+            "-skip-packages:akka.pattern",
+            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/",
+            "-skip-packages",
+            "akka.pattern")
       },
     Compile / doc / scalacOptions --= Seq("-Xfatal-warnings"),
     scalafmtOnCompile := true,

project/Dependencies.scala

@@ -2,13 +2,17 @@ import sbt._
 import Keys._
 
 object Dependencies {
+  // Java Platform version for JavaDoc creation
+  // sync with Java version in .github/workflows/publish.yml#documentation
+  val JavaDocLinkVersion = 17
+
   val Scala213 = "2.13.14"
   val Scala3 = "3.3.3"
   val Scala2Versions = Seq(Scala213)
   val ScalaVersions = Dependencies.Scala2Versions :+ Dependencies.Scala3
 
   val AkkaVersion = System.getProperty("override.akka.version", "2.9.3")
-  val AkkaVersionInDocs = AkkaVersion.take(3)
+  val AkkaVersionInDocs = VersionNumber(AkkaVersion).numbers match { case Seq(major, minor, _*) => s"$major.$minor" }
   val CassandraVersionInDocs = "4.0"
   // Should be sync with the version of the driver in Alpakka Cassandra
   val CassandraDriverVersion = "4.17.0"

project/link-validator.conf

@@ -2,20 +2,24 @@
 site-link-validator {
   root-dir = "./docs/target/site/"
   # relative to `root-dir`
-  start-file = "docs/akka-persistence-cassandra/snapshot/index.html"
+  start-file = "libraries/akka-persistence-cassandra/snapshot/index.html"
 
   # Resolves URLs with the given prefix as local files instead
   link-mappings = [
     {
-      prefix = "https://doc.akka.io/docs/akka-persistence-cassandra/snapshot/"
-      replace = "/docs/akka-persistence-cassandra/snapshot/"
+      prefix = "https://doc.akka.io/libraries/akka-persistence-cassandra/snapshot/"
+      replace = "/libraries/akka-persistence-cassandra/snapshot/"
     }
     {
       prefix = "https://doc.akka.io/api/akka-persistence-cassandra/snapshot/"
       replace = "/api/akka-persistence-cassandra/snapshot/"
     }
   ]
 
+  ignore-missing-local-files-regex = ""
+
+  ignore-files = []
+
   ignore-prefixes = [
     # GitHub will block with "429 Too Many Requests"
     "https://github.com/",

project/project-info.conf

@@ -26,10 +26,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} {