docs: revise URL structure (libraries), part 2 (#1981)

.github/workflows/build-test.yml

@@ -259,31 +259,3 @@ jobs:
         run: |-
           cd plugin-tester-scala
           mvn -nsu -ntp -Dakka.grpc.project.version=`cat ~/.version` dependency:unpack@unpack akka-grpc:generate scala:compile
-
-  test-docs:
-    name: Docs
-    runs-on: ubuntu-22.04
-    steps:
-      - name: Checkout
-        # https://github.com/actions/checkout/releases
-        # v4.1.1
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
-        with:
-          fetch-depth: 0
-
-      - name: Cache Coursier cache
-        # https://github.com/coursier/cache-action/releases
-        # v6.4.5
-        uses: coursier/cache-action@1ff273bff02a8787bc9f1877d347948af647956d
-
-      - 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: Test Maven Java
-        run: |-
-          cp .jvmopts-ghactions .jvmopts
-          sbt paradox

.github/workflows/link-validator.yml

@@ -1,8 +1,10 @@
 name: Link Validator
 
 on:
+  workflow_dispatch:
+  pull_request:
   schedule:
-    - cron:  '0 6 * * 1'
+    - cron:  '0 6 1 * *'
 
 permissions:
   contents: read
@@ -33,10 +35,12 @@ jobs:
           apps: cs
 
       - name: sbt site
-        run: sbt akka-grpc-docs/makeSite
+        run: |
+          cp .jvmopts-ghactions .jvmopts
+          sbt akka-grpc-docs/makeSite
 
       - name: Run Link Validator
         run: |
-          VERSION=$(ls docs/target/site/docs/akka-grpc)
+          VERSION=$(ls docs/target/site/libraries/akka-grpc)
           sed -e "s/snapshot/$VERSION/" scripts/link-validator.conf > /tmp/link-validator.conf
-          cs launch net.runne::site-link-validator:0.2.3 -- /tmp/link-validator.conf
+          cs launch net.runne::site-link-validator:0.2.5 -- /tmp/link-validator.conf

.github/workflows/publish.yml

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

build.sbt

@@ -200,7 +200,7 @@ lazy val docs = Project(id = "akka-grpc-docs", base = file("docs"))
     publish / skip := true,
     previewPath := (Paradox / siteSubdirName).value,
     Preprocess / siteSubdirName := s"api/akka-grpc/${projectInfoVersion.value}",
-    Paradox / siteSubdirName := s"docs/akka-grpc/${projectInfoVersion.value}",
+    Paradox / siteSubdirName := s"libraries/akka-grpc/${projectInfoVersion.value}",
     // Make sure code generation is ran before paradox:
     (Compile / paradox) := (Compile / paradox).dependsOn(Compile / compile).value,
     paradoxGroups := Map("Language" -> Seq("Java", "Scala"), "Buildtool" -> Seq("sbt", "Gradle", "Maven")),

docs/release-train-issue-template.md

@@ -39,7 +39,7 @@ Variables to be expanded in this template:
          ```
          cd ~/www
          git status
-         git add docs/akka-grpc/current docs/akka-grpc/$VERSION$
+         git add libraries/akka-grpc/current libraries/akka-grpc/$VERSION$
          git add api/akka-grpc/current api/akka-grpc/$VERSION$
          git commit -m "Akka gRPC $VERSION$"
          ```

project/Common.scala

@@ -97,14 +97,18 @@ object Common extends AutoPlugin {
         },
         "-doc-canonical-base-url",
         "https://doc.akka.io/api/akka-grpc/current/") ++
-      (if (scalaVersion.value.startsWith("2"))
+      (if (scalaBinaryVersion.value.startsWith("3")) {
          Seq(
+           s"-external-mappings:https://docs.oracle.com/en/java/javase/${Dependencies.JavaDocLinkVersion}/docs/api/java.base/")
+       } else if (isJdk17orHigher) {
+         Seq(
+           "-jdk-api-doc-base",
+           s"https://docs.oracle.com/en/java/javase/${Dependencies.JavaDocLinkVersion}/docs/api/java.base/",
            "-skip-packages",
-           "akka.pattern:" + // for some reason Scaladoc creates this
-           "templates")
-       else {
-         // Scala 3
-         Seq.empty
+           "akka.pattern")
+       } else {
+         Seq("-skip-packages", "akka.pattern")
+
        }),
     Compile / doc / scalacOptions -= "-Xfatal-warnings",
     Compile / doc / javacOptions := Seq.empty,
@@ -120,4 +124,7 @@ object Common extends AutoPlugin {
       throw new IllegalArgumentException("JDK 11 or higher is required")
     result
   }
+
+  val isJdk17orHigher: Boolean =
+    VersionNumber(sys.props("java.specification.version")).matchesSemVer(SemanticSelector(">=17"))
 }

project/Dependencies.scala

@@ -5,6 +5,11 @@ import sbt.Keys._
 import buildinfo.BuildInfo
 
 object Dependencies {
+
+  // Java Platform version for JavaDoc creation
+  // sync with Java version in .github/workflows/release.yml#documentation
+  lazy val JavaDocLinkVersion = 17
+
   object Versions {
     val scala212 = "2.12.19"
     val scala213 = "2.13.14"
@@ -20,7 +25,7 @@ object Dependencies {
     val akka = "2.10.0-M1"
     val akkaBinary = VersionNumber(akka).numbers match { case Seq(major, minor, _*) => s"$major.$minor" }
     val akkaHttp = "10.7.0-M1"
-    val akkaHttpBinary = "10.6"
+    val akkaHttpBinary = VersionNumber(akkaHttp).numbers match { case Seq(major, minor, _*) => s"$major.$minor" }
 
     val grpc = "1.63.2" // checked synced by VersionSyncCheckPlugin
 

project/project-info.conf

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

scripts/link-validator.conf

@@ -1,13 +1,13 @@
 site-link-validator {
   root-dir = "./docs/target/site/"
   # relative to `root-dir`
-  start-file = "docs/akka-grpc/snapshot/index.html"
+  start-file = "libraries/akka-grpc/snapshot/index.html"
 
   # Resolves URLs with the given prefix as local files instead
   link-mappings = [
     {
       prefix = "https://doc.akka.io/libraries/akka-grpc/snapshot/"
-      replace = "/docs/akka-grpc/snapshot/"
+      replace = "/libraries/akka-grpc/snapshot/"
     }
     {
       prefix = "https://doc.akka.io/api/akka-grpc/snapshot/"
@@ -17,11 +17,14 @@ site-link-validator {
 
   ignore-missing-local-files-regex = ""
 
+  ignore-files = []
+
   ignore-prefixes = [
     # GitHub will block with "429 Too Many Requests"
     "https://github.com/akka/akka-grpc/"
     # MVN repository forbids access after a few requests
     "https://mvnrepository.com/artifact/"
+    "https://repo.akka.io/"
   ]
 
   non-https-whitelist = []