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

.github/workflows/build-test.yml

@@ -14,7 +14,7 @@ jobs:
   check-code-style:
     name: Checks
     runs-on: ubuntu-22.04
-    if: github.repository == 'akka/akka-diagnostics'
+    if: github.event.repository.fork == false
     steps:
       - name: Checkout
         # https://github.com/actions/checkout/releases
@@ -49,7 +49,7 @@ jobs:
   test:
     name: Run tests
     runs-on: ubuntu-22.04
-    if: github.repository == 'akka/akka-diagnostics'
+    if: github.event.repository.fork == false
     strategy:
       fail-fast: false
       matrix:
@@ -88,36 +88,3 @@ jobs:
         run: |-
           cp .jvmopts-ci .jvmopts
           sbt test
-
-  check-docs:
-    name: Check Docs
-    runs-on: ubuntu-22.04
-    if: github.repository == 'akka/akka-diagnostics'
-    steps:
-      - name: Checkout
-        # https://github.com/actions/checkout/releases
-        # v4.1.1
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
-        with:
-          fetch-depth: 0
-
-      - name: Checkout GitHub merge
-        if: github.event.pull_request
-        run: |-
-          git fetch origin pull/${{ github.event.pull_request.number }}/merge:scratch
-          git checkout scratch
-
-      - 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
-
-      - name: Create all API docs for artifacts/website and all reference docs
-        run: sbt "unidoc; docs/paradox"

.github/workflows/link-validator.yml

@@ -0,0 +1,47 @@
+name: Link Validator
+
+on:
+  workflow_dispatch:
+  pull_request:
+  schedule:
+    - cron:  '0 4 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 for artifacts/website and all reference docs
+        run: sbt "unidoc; docs/paradox"
+
+      - name: Run Link Validator
+        run: cs launch net.runne::site-link-validator:0.2.5 -- project/link-validator.conf

.github/workflows/publish.yml

@@ -58,12 +58,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

@@ -14,7 +14,7 @@ The Akka Config Checker tries to help you by finding potential configuration iss
 
 ## Documentation
 
-The documentation can be found [here](https://doc.akka.io/docs/akka-diagnostics/current/index.html).
+The documentation can be found [here](https://doc.akka.io/libraries/akka-diagnostics/current/index.html).
 
 ## Project status
 
@@ -26,4 +26,4 @@ For questions please use the [discuss.akka.io](https://discuss.akka.io).
 
 Akka is licensed under the Business Source License 1.1, please see the [Akka License FAQ](https://www.lightbend.com/akka/license-faq).
 
-Tests and documentation are under a separate license, see the LICENSE file in each documentation and test root directory for details.
+Tests and documentation are under a separate license, see the LICENSE file in each documentation and test root directory for details.

akka-diagnostics/src/main/scala/akka/diagnostics/ConfigChecker.scala

@@ -867,7 +867,7 @@ class ConfigChecker(system: ExtendedActorSystem, config: Config, reference: Conf
         warn(
           checkerKey,
           path,
-          "Deploying an actor remotely is deprecated and not supported. As per https://doc.akka.io/docs/akka/current/remoting.html#creating-actors-remotely")
+          "Deploying an actor remotely is deprecated and not supported. As per https://doc.akka.io/libraries/akka-core/current/remoting.html#creating-actors-remotely")
       else Nil
     }
 

akka-diagnostics/src/main/scala/akka/diagnostics/StarvationDetector.scala

@@ -342,7 +342,7 @@ object StarvationDetector {
           catch {
             case e: InaccessibleObjectException =>
               log.warning(s"Stopping Starvation detector. Reason: ${e.getMessage}. \n" +
-              s"Probably you are missing some JVM parameters. See 'note' in https://doc.akka.io/docs/akka-diagnostics/current/starvation-detector.html#configuration")
+              s"Probably you are missing some JVM parameters. See 'note' in https://doc.akka.io/libraries/akka-diagnostics/current/starvation-detector.html#configuration")
               return
             case NonFatal(ex) =>
               log.error(

build.sbt

@@ -19,7 +19,7 @@ inThisBuild(
   Seq(
     organization := "com.lightbend.akka",
     organizationName := "Lightbend Inc.",
-    homepage := Some(url("https://doc.akka.io/docs/akka-diagnostics/current")),
+    homepage := Some(url("https://doc.akka.io/libraries/akka-diagnostics/current")),
     scmInfo := Some(
       ScmInfo(url("https://github.com/akka/akka-diagnostics"), "https://github.com/akka/akka-diagnostics.git")),
     startYear := Some(2022),
@@ -36,7 +36,7 @@ inThisBuild(
       val tagOrBranch =
         if (isSnapshot.value) "main"
         else "v" + version.value
-      Seq(("BUSL-1.1", url(s"https://raw.githubusercontent.com/akka/akka-diagnostics/${tagOrBranch}/LICENSE")))
+      Seq(("BUSL-1.1", url(s"https://github.com/akka/akka-diagnostics/blob/${tagOrBranch}/LICENSE")))
     },
     description := "Akka diagnostics tools and utilities",
     // append -SNAPSHOT to version when isSnapshot
@@ -64,6 +64,29 @@ lazy val common: Seq[Setting[_]] =
       else
         scalacOptionsBase
     },
+    Compile / doc / scalacOptions := scalacOptions.value ++ Seq(
+      "-doc-title",
+      "Akka Dependencies",
+      "-doc-version",
+      version.value,
+      "-sourcepath",
+      (ThisBuild / baseDirectory).value.toString,
+      "-doc-source-url", {
+        val branch = if (isSnapshot.value) "main" else s"v${version.value}"
+        s"https://github.com/akka/akka-diagnostics/tree/${branch}€{FILE_PATH_EXT}#L€{FILE_LINE}"
+      },
+      "-doc-canonical-base-url",
+      "https://doc.akka.io/api/akka-diagnostics/current/")
+    ++ {
+      // 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/")
+    },
     Test / logBuffered := false,
     Test / parallelExecution := false,
     // show full stack traces and test case durations
@@ -115,18 +138,18 @@ lazy val docs = (project in file("docs"))
     Paradox / siteSubdirName := s"docs/akka-diagnostics/${if (isSnapshot.value) "snapshot" else version.value}",
     Compile / paradoxProperties ++= Map(
       "version" -> version.value,
-      "project.url" -> "https://doc.akka.io/docs/akka-diagnostics/current/",
-      "canonical.base_url" -> "https://doc.akka.io/docs/akka-diagnostics/current",
+      "project.url" -> "https://doc.akka.io/libraries/akka-diagnostics/current/",
+      "canonical.base_url" -> "https://doc.akka.io/libraries/akka-diagnostics/current",
       "akka.version" -> Dependencies.AkkaVersion,
       "scala.version" -> scalaVersion.value,
       "scala.binaryVersion" -> scalaBinaryVersion.value,
       "extref.scaladoc.base_url" -> s"/${(Preprocess / siteSubdirName).value}/",
       "extref.javadoc.base_url" -> s"/japi/akka-diagnostics/${if (isSnapshot.value) "snapshot" else version.value}",
       "scaladoc.akka.persistence.gdpr.base_url" -> s"/api/akka-diagnostics/${if (isSnapshot.value) "snapshot"
       else version.value}",
-      "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}",
-      "extref.akka-http.base_url" -> s"https://doc.akka.io/docs/akka-http/${Dependencies.AkkaHttpVersionInDocs}/%s",
+      "extref.akka-http.base_url" -> s"https://doc.akka.io/libraries/akka-http/${Dependencies.AkkaHttpVersionInDocs}/%s",
       "scaladoc.akka.http.base_url" -> s"https://doc.akka.io/api/akka-http/${Dependencies.AkkaHttpVersionInDocs}/",
       "snip.github_link" -> "false"),
     ApidocPlugin.autoImport.apidocRootPackage := "akka",

docs/release-train-issue-template.md

@@ -29,7 +29,7 @@ Key links:
 ### Check availability
 
 - [ ] Check [API](https://doc.akka.io/api/akka-diagnostics/$VERSION$/) documentation
-- [ ] Check [reference](https://doc.akka.io/docs/akka-diagnostics/$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-diagnostics/$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/lightbend/akka/akka-diagnostics_2.13/$VERSION$/akka-diagnostics_2.13-$VERSION$.pom
 
 ### When everything is on https://repo.akka.io/maven
@@ -39,7 +39,7 @@ Key links:
          ```
          cd ~/www
          git status
-         git add docs/akka-diagnostics/current docs/akka-diagnostics/$VERSION$
+         git add libraries/akka-diagnostics/current libraries/akka-diagnostics/$VERSION$
          git add api/akka-diagnostics/current api/akka-diagnostics/$VERSION$
          git commit -m "Akka Diagnostics $VERSION$"
          ```
@@ -50,7 +50,6 @@ For important patch releases, and only if critical issues have been fixed:
 
 - [ ] Send a release notification to [Lightbend discuss](https://discuss.akka.io)
 - [ ] Tweet using the [@akkateam](https://twitter.com/akkateam/) account (or ask someone to) about the new release
-- [ ] Announce on [Gitter akka/akka](https://gitter.im/akka/akka)
 - [ ] Announce internally (with links to Tweet, discuss)
 
 For minor or major releases:
@@ -59,5 +58,5 @@ 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 the akka-dependencies bom and version for [Akka module versions](https://doc.akka.io/libraries/akka-dependencies/current/) in [akka-dependencies repo](https://github.com/akka/akka-dependencies)
 - Close this issue

docs/src/main/paradox/.htaccess

@@ -1,2 +1,2 @@
 # Sample redirect when renaming pages
-# RedirectMatch 301 ^/docs/akka-diagnostics/([^/]+)/release-notes/1.0.html https://doc.akka.io/docs/akka-diagnostics/$1/release-notes/1.0.x.html
+# RedirectMatch 301 ^/docs/akka-diagnostics/([^/]+)/release-notes/1.0.html https://doc.akka.io/libraries/akka-diagnostics/$1/release-notes/1.0.x.html

docs/src/main/paradox/config-checker.md

@@ -13,7 +13,7 @@ seen in mailing lists and customer consulting.
 
 The advice the tool can give is of course of general character and there will always be
 cases where it is wrong and the given configuration is appropriate for the specific
-system. Do not hesitate to use [Lightbend Support](http://support.lightbend.com/) if
+system. Do not hesitate to use [Lightbend Support](https://support.lightbend.com/) if
 you need more advice or discussion.
 
 As a general rule; use default values until you have a problem or are sure that the
@@ -305,7 +305,7 @@ Don't use too small pool size [1] for the default-remote-dispatcher-size. Relate
 ### create-actor-remotely 
 
 ```
-Deploying an actor remotely is deprecated and not supported. As per https://doc.akka.io/docs/akka/current/remoting.html#creating-actors-remotely Related config properties: [akka.actor.deployment."/...".remote"]. You may disable this check by adding [create-actor-remotely] to configuration string list akka.diagnostics.checker.disabled-checks.
+Deploying an actor remotely is deprecated and not supported. As per https://doc.akka.io/libraries/akka-core/current/remoting.html#creating-actors-remotely Related config properties: [akka.actor.deployment."/...".remote"]. You may disable this check by adding [create-actor-remotely] to configuration string list akka.diagnostics.checker.disabled-checks.
 ```
 
 ### remote-artery-disabled

project/Dependencies.scala

@@ -4,12 +4,16 @@
 import sbt._
 
 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 CrossScalaVersions = Seq(Scala213, Scala3)
 
   val AkkaVersion = "2.9.3"
-  val AkkaVersionInDocs = AkkaVersion.take(3)
+  val AkkaVersionInDocs = VersionNumber(AkkaVersion).numbers match { case Seq(major, minor, _*) => s"$major.$minor" }
   val AkkaHttpVersionInDocs = "10.6"
   val ScalaTestVersion = "3.2.18"
 

project/link-validator.conf

@@ -0,0 +1,32 @@
+// config for https://github.com/ennru/site-link-validator/
+site-link-validator {
+  root-dir = "./docs/target/paradox/site/main/"
+  # relative to `root-dir`
+  start-file = "index.html"
+
+  # Resolves URLs with the given prefix as local files instead
+  link-mappings = [
+    {
+      prefix = "https://doc.akka.io/libraries/akka-diagnostics/snapshot/"
+      replace = "/libraries/akka-diagnostics/snapshot/"
+    }
+    {
+      prefix = "https://doc.akka.io/api/akka-diagnostics/snapshot/"
+      replace = "/api/akka-diagnostics/snapshot/"
+    }
+  ]
+
+  ignore-missing-local-files-regex = ""
+
+  ignore-files = []
+
+  ignore-prefixes = [
+    # GitHub will block with "429 Too Many Requests"
+    "https://github.com/",
+    "https://repo.akka.io/"
+    "https://support.lightbend.com/"
+  ]
+
+  non-https-whitelist = [
+  ]
+}

project/plugins.sbt

@@ -4,6 +4,6 @@ addSbtPlugin("org.scalameta" % "sbt-scalafmt" % "2.5.2")
 addSbtPlugin("com.lightbend.paradox" % "sbt-paradox-dependencies" % "0.2.4")
 addSbtPlugin("com.lightbend.akka" % "sbt-paradox-akka" % "0.57")
 addSbtPlugin("com.typesafe.sbt" % "sbt-site" % "1.4.1")
-addSbtPlugin("com.lightbend.sbt" % "sbt-publish-rsync" % "0.2")
+addSbtPlugin("com.lightbend.sbt" % "sbt-publish-rsync" % "0.3")
 addSbtPlugin("com.lightbend.sbt" % "sbt-java-formatter" % "0.8.0")
 addSbtPlugin("com.github.sbt" % "sbt-ci-release" % "1.6.1")

project/project-info.conf

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