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

* docs: revise URL structure (libraries)
* Use sbt's Version matcher for binary versions
* Use link-validator; configure JavaDoc

.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-management'
+    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

README.md

@@ -8,7 +8,7 @@ Future additions may extend these concepts to other parts of Akka.
 Documentation
 -------------
 
-See [reference](https://doc.akka.io/docs/akka-management/current/) and [API](https://doc.akka.io/api/akka-management/current/akka/management/index.html)
+See [reference](https://doc.akka.io/libraries/akka-management/current/) and [API](https://doc.akka.io/api/akka-management/current/akka/management/index.html)
 
 Contributions & Maintainers
 ---------------------------

build.sbt

@@ -366,20 +366,20 @@ lazy val docs = project
       ),
     previewPath := (Paradox / siteSubdirName).value,
     paradoxGroups := Map("Language" -> Seq("Java", "Scala")),
-    Paradox / siteSubdirName := s"docs/akka-management/${if (isSnapshot.value) "snapshot" else version.value}",
+    Paradox / siteSubdirName := s"libraries/akka-management/${if (isSnapshot.value) "snapshot" else version.value}",
     Compile / paradoxProperties ++= Map(
         "date.year" -> Common.currentYear,
-        "project.url" -> "https://doc.akka.io/docs/akka-management/current/",
-        "canonical.base_url" -> "https://doc.akka.io/docs/akka-management/current",
+        "project.url" -> "https://doc.akka.io/libraries/akka-management/current/",
+        "canonical.base_url" -> "https://doc.akka.io/libraries/akka-management/current",
         "scala.binary.version" -> scalaBinaryVersion.value,
         "akka.version" -> Dependencies.AkkaVersion,
         "akka.binary.version" -> Dependencies.AkkaBinaryVersion,
-        "extref.akka.base_url" -> s"https://doc.akka.io/docs/akka/current/%s",
-        "scaladoc.akka.base_url" -> s"https://doc.akka.io/api/akka/current/",
-        "extref.akka-http.base_url" -> s"https://doc.akka.io/docs/akka-http/${Dependencies.AkkaHttpBinaryVersion}/%s",
+        "extref.akka.base_url" -> s"https://doc.akka.io/libraries/akka-core/current/%s",
+        "scaladoc.akka.base_url" -> s"https://doc.akka.io/api/akka-core/current/",
+        "extref.akka-http.base_url" -> s"https://doc.akka.io/libraries/akka-http/${Dependencies.AkkaHttpBinaryVersion}/%s",
         "scaladoc.akka.http.base_url" -> s"https://doc.akka.io/api/akka-http/${Dependencies.AkkaHttpBinaryVersion}/",
-        "extref.akka-grpc.base_url" -> s"https://doc.akka.io/docs/akka-grpc/current/%s",
-        "extref.akka-enhancements.base_url" -> s"https://doc.akka.io/docs/akka-enhancements/current/%s",
+        "extref.akka-grpc.base_url" -> s"https://doc.akka.io/libraries/akka-grpc/current/%s",
+        "extref.akka-enhancements.base_url" -> s"https://doc.akka.io/libraries/akka-enhancements/current/%s",
         "scaladoc.akka.management.base_url" -> s"/${(Preprocess / siteSubdirName).value}/"
       ),
     publishRsyncArtifacts += makeSite.value -> "www/",

docs/release-train-issue-template.md

@@ -27,7 +27,7 @@ Variables to be expanded in this template:
 ### Check availability
 
 - [ ] Check [API](https://doc.akka.io/api/akka-management/$VERSION$/) documentation
-- [ ] Check [reference](https://doc.akka.io/docs/akka-management/$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-management/$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/management/akka-management_2.13/$VERSION$/akka-management_2.13-$VERSION$.pom
 
 ### When everything is on https://repo.akka.io/maven
@@ -37,7 +37,7 @@ Variables to be expanded in this template:
          ```
          cd ~/www
          git status
-         git add docs/akka-management/current docs/akka-management/$VERSION$
+         git add libraries/akka-management/current libraries/akka-management/$VERSION$
          git add api/akka-management/current api/akka-management/$VERSION$
          git commit -m "Akka Management $VERSION$"
          ```
@@ -56,7 +56,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 Guide samples](https://github.com/lightbend/akka-guide)
 - Close this issue
 

docs/src/main/paradox/.htaccess

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

docs/src/main/paradox/bootstrap/istio.md

@@ -4,7 +4,7 @@
 
 To bootstrap an Akka cluster in Istio, Istio must be configured to allow Akka cluster communication to bypass the Istio sidecar proxy. Istio's routing design is made such that services don't need to be aware of each others location, they just communicate with the proxy, and the mesh figures out how to route and secure the communication. However, Akka cluster communication is fundamentally location aware, in order to, for example, route messages to sharded actors. Hence a service mesh is not a suitable communication medium for cluster traffic, so it needs to be bypassed.
 
-It is important to be aware that since Istio's proxy is bypassed, the Akka cluster communication will not be secured by Istio using TLS. If you wish to secure your cluster communication, you will need to configure [Akka remoting with mTLS](https://doc.akka.io/docs/akka/current/remoting-artery.html#remote-security) yourself.
+It is important to be aware that since Istio's proxy is bypassed, the Akka cluster communication will not be secured by Istio using TLS. If you wish to secure your cluster communication, you will need to configure [Akka remoting with mTLS](https://doc.akka.io/libraries/akka-core/current/remoting-artery.html#remote-security) yourself.
 
 Booting an Akka cluster in Istio requires a minimum Istio version of 1.2.0, as it requires the outbound port exclusions feature that was added in there. It also requires using the @ref[Kubernetes API](kubernetes-api.md) contact point discovery method to be used. The instructions below are for the additional configuration necessary to ensure an Akka cluster can be bootstrapped in Istio.
 
@@ -72,4 +72,4 @@ spec:
           httpGet:
             path: "/alive"
             port: management
-```
+```

docs/src/main/paradox/discovery/kubernetes.md

@@ -118,7 +118,7 @@ spec:
 
 ### Role-Based Access Control
 
-If your Kubernetes cluster has [Role-Based Access Control (RBAC)](https://kubernetes.io/docs/admin/authorization/rbac/)
+If your Kubernetes cluster has [Role-Based Access Control (RBAC)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
 enabled, you'll also have to grant the Service Account that your pods run under access to list pods. The following
 configuration can be used as a starting point. It creates a `Role`, `pod-reader`, which grants access to query pod
 information. It then binds the default Service Account to the `Role` by creating a `RoleBinding`.

docs/src/main/paradox/kubernetes-deployment/building-using-maven.md

@@ -99,7 +99,7 @@ To build and publish the image run the following. The Docker username and regist
 
 Note that the registry to push to must include the username, for example `-Ddocker.registry=docker.io/youruser`.
 
-Security information (i.e. user and password) can be specified in multiple ways as described in section [docker-maven-plugin authentication](http://dmp.fabric8.io/#authentication).
+Security information (i.e. user and password) can be specified in multiple ways as described in section [docker-maven-plugin authentication](https://dmp.fabric8.io/#authentication).
 
 ```
 mvn -Ddocker.username=<user> -Ddocker.registry=<registry>/<user> package docker:push

docs/src/main/paradox/kubernetes-deployment/building-using-sbt.md

@@ -34,7 +34,7 @@ We recommend using the Eclipse Temurin 17 base image:
 dockerBaseImage := "docker.io/library/eclipse-temurin:17-jre"
 ```
 
-For a full list of Lightbend certified JDK builds and versions, see [here](https://doc.akka.io/docs/akka-dependencies/current/java-versions.html).
+For a full list of Lightbend certified JDK builds and versions, see [here](https://doc.akka.io/libraries/akka-dependencies/current/java-versions.html).
 
 ### Git hash based version numbers
 

docs/src/main/paradox/kubernetes-deployment/deploying.md

@@ -61,7 +61,7 @@ make the logs quieter, but for now it will help us to understand what is happeni
 
 1  [INFO] [akka.remote.artery.tcp.ArteryTcpTransport]  - Remoting started with transport [Artery tcp]; listening on address [akka://[email protected]:25520] with UID [4609278524397890522] MDC: {akkaAddress=akka://[email protected]:25520, sourceThread=main, akkaSource=ArteryTcpTransport(akka://Appka), sourceActorSystem=Appka, akkaTimestamp=10:04:51.188UTC}
    [INFO] [akka.cluster.Cluster] [] [Appka-akka.actor.default-dispatcher-3] - Cluster Node [akka://[email protected]:25520] - Starting up, Akka version [2.6.5] ... MDC: {akkaAddress=akka://[email protected]:25520, sourceThread=main, akkaSource=Cluster(akka://Appka), sourceActorSystem=Appka, akkaTimestamp=10:04:51.240UTC}
-   [INFO] [akka.cluster.Cluster] [] [Appka-akka.actor.default-dispatcher-6] - Cluster Node [akka://[email protected]:25520] - No seed-nodes configured, manual cluster join required, see https://doc.akka.io/docs/akka/current/typed/cluster.html#joining MDC: {akkaAddress=akka://[email protected]:25520, sourceThread=Appka-akka.actor.internal-dispatcher-5, akkaSource=Cluster(akka://Appka), sourceActorSystem=Appka, akkaTimestamp=10:04:51.619UTC}
+   [INFO] [akka.cluster.Cluster] [] [Appka-akka.actor.default-dispatcher-6] - Cluster Node [akka://[email protected]:25520] - No seed-nodes configured, manual cluster join required, see https://doc.akka.io/libraries/akka-core/current/typed/cluster.html#joining MDC: {akkaAddress=akka://[email protected]:25520, sourceThread=Appka-akka.actor.internal-dispatcher-5, akkaSource=Cluster(akka://Appka), sourceActorSystem=Appka, akkaTimestamp=10:04:51.619UTC}
    [INFO] [akka.cluster.bootstrap.demo.DemoApp] [] [Appka-akka.actor.default-dispatcher-6] - Started [akka://Appka], cluster.selfAddress = akka://[email protected]:25520) MDC: {akkaAddress=akka://[email protected]:25520, akkaSource=akka://Appka/user, sourceActorSystem=Appka}
 
 2a [INFO] [akka.management.internal.HealthChecksImpl] [] [Appka-akka.actor.default-dispatcher-3] - Loading readiness checks [(cluster-membership,akka.management.cluster.scaladsl.ClusterMembershipCheck), (example-ready,akka.cluster.bootstrap.demo.DemoHealthCheck)] MDC: {akkaAddress=akka://[email protected]:25520, sourceThread=Appka-akka.actor.default-dispatcher-6, akkaSource=HealthChecksImpl(akka://Appka), sourceActorSystem=Appka, akkaTimestamp=10:04:53.510UTC}
@@ -150,7 +150,7 @@ for 'hello world':
 
     kubectl expose deployment appka --type=LoadBalancer --name=appka-service
 
-You can inspect the Akka Cluster membership status with the [Cluster HTTP Management](https://doc.akka.io/docs/akka-management/current/cluster-http-management.html).
+You can inspect the Akka Cluster membership status with the @ref:[Cluster HTTP Management](../cluster-http-management.md).
 
     curl http://127.0.0.1:8558/cluster/members/
 

docs/src/main/paradox/kubernetes-deployment/preparing-for-production.md

@@ -66,14 +66,14 @@ spec:
 Here are a few things to note:
 
 * We're using a Kubernetes deployment. Deployments are logical groupings of pods that represent a single service using the same template. 
-  They support [configurable rolling updates](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/#deploymentstrategy-v1-apps), 
+  They support configurable rolling updates, 
   meaning the cluster will be gradually upgraded, rather than upgrading every node at once and incurring an outage. Be sure to consult @ref:[Kubernetes Rolling Updates](../rolling-updates.md#kubernetes-rolling-updates) for recommendations.
 * We label the pod in the `template` with `app: appka`. This must match the ActorSystem name so that @ref[Akka Bootstrap](../bootstrap/index.md) finds the other nodes in the cluster.
 * The image we're using is `akka-sample-cluster-kubernetes:latest`. This corresponds to the name and version of the service in our build. 
   We will discuss how to select an appropriate version number below.
 * We've only requested minimal CPU to the pods for this service. This is suitable for a local deployment, but you may wish to increase it if you're 
   deploying to a real deployment. Note that we also haven't set a CPU limit, this is because it's 
-  [recommended that JVMs do not set a CPU limit](https://doc.akka.io/docs/akka/current/additional/deploying.html#resource-limits).
+  [recommended that JVMs do not set a CPU limit](https://doc.akka.io/libraries/akka-core/current/additional/deploying.html#resource-limits).
 * We've configured a liveness probe and readiness probe. These are provided out of the box by Akka Management and are discussed later.
 
 ## Image version number

docs/src/main/paradox/kubernetes-lease.md

@@ -7,7 +7,7 @@ The API, configuration and behavior may change based on feedback from initial us
 
 @@@
 
-This module is an implementation of an [Akka Coordination Lease](https://doc.akka.io/docs/akka/current/coordination.html#lease) backed 
+This module is an implementation of an [Akka Coordination Lease](https://doc.akka.io/libraries/akka-core/current/coordination.html#lease) backed 
 by a [Custom Resource Definition (CRD)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) in Kubernetes.
 Resources in Kubernetes offer [concurrency control and consistency](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) 
 that have been used to build a distributed lease/lock.

docs/src/main/paradox/loglevels/log4j2.md

@@ -71,7 +71,7 @@ curl -X PUT "http://127.0.0.1:8558/loglevel/log4j2?logger=com.example.MyActor&le
 
 #### Classic and Internal Akka Logger Level
 
-Internal Akka actors and classic Akka does logging through the built in API there is an [additional level of filtering](https://doc.akka.io/docs/akka/current/logging.html#slf4j) using the
+Internal Akka actors and classic Akka does logging through the built in API there is an [additional level of filtering](https://doc.akka.io/libraries/akka-core/current/logging.html#slf4j) using the
 `akka.loglevel` setting. If you have not set `akka.loglevel` to `DEBUG` (recommended) log entries from the classic logging API may never reach the logger backend at all.
 
 The current level configured with `akka.loglevel` can be inspected with a GET request to `loglevel/akka`.

docs/src/main/paradox/loglevels/logback.md

@@ -6,7 +6,7 @@ Dynamic Log Levels for Logback hooks into Akka Management and provides a route w
 
 @@project-info{ projectId="loglevels-logback" }
 
-Requires @ref:[Akka Management](../akka-management.md) and that the application uses [Logback](http://logback.qos.ch) as logging backend.
+Requires @ref:[Akka Management](../akka-management.md) and that the application uses [Logback](https://logback.qos.ch) as logging backend.
 
 The Akka dependencies are available from Akka's library repository. To access them there, you need to configure the URL for this repository.
 
@@ -71,7 +71,7 @@ curl -X PUT "http://127.0.0.1:8558/loglevel/logback?logger=com.example.MyActor&l
 
 #### Classic and Internal Akka Logger Level
 
-Internal Akka actors and classic Akka does logging through the built in API there is an [additional level of filtering](https://doc.akka.io/docs/akka/current/logging.html#slf4j) using the
+Internal Akka actors and classic Akka does logging through the built in API there is an [additional level of filtering](https://doc.akka.io/libraries/akka-core/current/logging.html#slf4j) using the
 `akka.loglevel` setting. If you have not set `akka.loglevel` to `DEBUG` (recommended) log entries from the classic logging API may never reach the logger backend at all.
 
 The current level configured with `akka.loglevel` can be inspected with a GET request to `loglevel/akka`.

docs/src/main/paradox/rolling-updates.md

@@ -206,7 +206,7 @@ roleRef:
 
 ## app-version from Deployment
 
-When using Cluster Sharding, it is [recommended](https://doc.akka.io/docs/akka/current/additional/rolling-updates.html#cluster-sharding) to define an increasing `akka.cluster.app-version` configuration property for each roll out. 
+When using Cluster Sharding, it is [recommended](https://doc.akka.io/libraries/akka-core/current/additional/rolling-updates.html#cluster-sharding) to define an increasing `akka.cluster.app-version` configuration property for each roll out. 
 
 This works well unless you use `kubectl rollout undo` which deploys the previous ReplicaSet configuration which contains the previous value for that config. 
 

lease-kubernetes/src/main/scala/akka/coordination/lease/kubernetes/internal/KubernetesApiImpl.scala

@@ -210,7 +210,7 @@ PUTs must contain resourceVersions. Response:
       .to[String]
       .map(body =>
         throw new LeaseException(
-          s"Unauthorized to communicate with Kubernetes API server. See https://doc.akka.io/docs/akka-management/current/kubernetes-lease.html#role-based-access-control for setting up access control. Body: $body"))
+          s"Unauthorized to communicate with Kubernetes API server. See https://doc.akka.io/libraries/akka-management/current/kubernetes-lease.html#role-based-access-control for setting up access control. Body: $body"))
   }
 
   private def pathForLease(name: String): Uri.Path =

native-image-tests/src/main/resources/logback.xml

@@ -1,6 +1,6 @@
 <configuration>
     <!-- This is a development logging configuration that logs to standard out, for an example of a production
-        logging config, see the Akka docs: https://doc.akka.io/docs/akka/2.6/typed/logging.html#logback -->
+        logging config, see the Akka docs: https://doc.akka.io/libraries/akka-core/2.6/typed/logging.html#logback -->
     <appender name="STDOUT" target="System.out" class="ch.qos.logback.core.ConsoleAppender">
         <encoder>
             <pattern>[%date{ISO8601}] [%level] [%logger] [%thread] [%X{akkaSource}] - %msg%n</pattern>