doc: Download zip files with samples, #1058

.github/workflows/release.yml

@@ -66,6 +66,7 @@ jobs:
 
       - name: Publish
         run: |-
+          scripts/prepare-downloads.sh
           eval "$(ssh-agent -s)"
           echo $AKKA_RSYNC_GUSTAV | base64 -d > .github/id_rsa
           chmod 600 .github/id_rsa

.gitignore

@@ -13,4 +13,8 @@ akka-projection-slick/src/it/resources/container-license-acceptance.txt
 
 .bsp
 .metals
-.vscode
+.vscode
+
+# attachments created by scripts/prepare-downloads.sh
+akka-distributed-cluster-docs/src/main/paradox/attachments
+akka-edge-docs/src/main/paradox/attachments

akka-distributed-cluster-docs/src/main/paradox/guide/1-event-sourced-shopping-cart.md

@@ -124,10 +124,10 @@ Java
 
 ## Running the sample
 
-The complete sample can be downloaded from GitHub, but note that it also includes the next step of the guide:
+The complete sample can be downloaded, but note that it also includes the next step of the guide:
 
-  * Java: https://github.com/akka/akka-projection/tree/main/samples/grpc/shopping-cart-service-java
-  * Scala: https://github.com/akka/akka-projection/tree/main/samples/grpc/shopping-cart-service-scala
+  * Java: [shopping-scala.zip](../attachments/shopping-scala.zip)
+  * Scala: [shopping-java.zip](../attachments/shopping-java.zip)
 
 Before running the sample locally you will need to run a PostgreSQL instance in docker, it can be started with the included
 `docker-compose.yml`. Run it and create the needed database schema:

akka-distributed-cluster-docs/src/main/paradox/guide/2-service-to-service.md

@@ -171,15 +171,10 @@ See @apidoc[akka.projection.grpc.consumer.ConsumerFilter] for full API documenta
 
 ## Complete Sample Projects
 
-The complete sample can be downloaded from GitHub, the shopping cart:
+The complete sample can be downloaded:
 
-* Java: https://github.com/akka/akka-projection/tree/main/samples/grpc/shopping-cart-service-java
-* Scala: https://github.com/akka/akka-projection/tree/main/samples/grpc/shopping-cart-service-scala
-
-And the consuming analytics service:
-
-* Java: https://github.com/akka/akka-projection/tree/main/samples/grpc/shopping-analytics-service-java
-* Scala: https://github.com/akka/akka-projection/tree/main/samples/grpc/shopping-analytics-service-scala
+* Java: [shopping-scala.zip](../attachments/shopping-scala.zip)
+* Scala: [shopping-java.zip](../attachments/shopping-java.zip)
 
 ## Running the sample code locally
 

akka-distributed-cluster-docs/src/main/paradox/guide/3-active-active.md

@@ -147,10 +147,10 @@ Java
 
 ## Complete Sample Projects
 
-The complete sample can be downloaded from GitHub, the replicated shopping cart:
+The complete sample can be downloaded:
 
-* Java: https://github.com/akka/akka-projection/tree/main/samples/replicated/shopping-cart-service-java
-* Scala: https://github.com/akka/akka-projection/tree/main/samples/replicated/shopping-cart-service-scala
+* Java: [replicated-shopping-scala.zip](../attachments/replicated-shopping-scala.zip)
+* Scala: [replicated-shopping-java.zip](../attachments/replicated-shopping-java.zip)
 
 ## Running the sample code locally
 

akka-distributed-cluster-docs/src/main/paradox/guide/4-deploying.md

@@ -131,12 +131,12 @@ If you haven't already, repeat the steps for namespace, rbac, database secret, a
 
 We are going to deploy the `shopping-cart-service` in region `us-east-2`.
 
-This step is for deploying:
+The complete sample can be downloaded:
 
-* Java: https://github.com/akka/akka-projection/tree/main/samples/grpc/shopping-cart-service-java
-* Scala: https://github.com/akka/akka-projection/tree/main/samples/grpc/shopping-cart-service-scala
+* Java: [shopping-scala.zip](../attachments/shopping-scala.zip)
+* Scala: [shopping-java.zip](../attachments/shopping-java.zip)
 
-Build the image:
+Build the image in `shopping-cart-service` directory:
 
 Scala
 :  ```
@@ -224,12 +224,12 @@ kubectl get services
 
 We are going to deploy the `shopping-analytics-service` in region `eu-central-1`.
 
-This step is for deploying:
+The complete sample can be downloaded:
 
-* Java: https://github.com/akka/akka-projection/tree/main/samples/grpc/shopping-analytics-service-java
-* Scala: https://github.com/akka/akka-projection/tree/main/samples/grpc/shopping-analytics-service-scala
+* Java: [shopping-scala.zip](../attachments/shopping-scala.zip)
+* Scala: [shopping-java.zip](../attachments/shopping-java.zip)
 
-Build the image:
+Build the image in `shopping-analytics-service` directory:
 
 Scala
 :  ```
@@ -282,10 +282,12 @@ Projection [cart-events-cart-768-1023] consumed ItemQuantityAdjusted for cart ca
 
 ## Deploy replicated shopping-cart-service
 
-This step is for deploying:
+This step is for deploying `replicated-shopping-cart-service`:
 
-* Java: https://github.com/akka/akka-projection/tree/main/samples/replicated/shopping-cart-service-java
-* Scala: https://github.com/akka/akka-projection/tree/main/samples/replicated/shopping-cart-service-scala
+The complete sample can be downloaded:
+
+* Java: [replicated-shopping-scala.zip](../attachments/replicated-shopping-scala.zip)
+* Scala: [replicated-shopping-java.zip](../attachments/replicated-shopping-java.zip)
 
 Now there will be connections in both directions, so install the @ref:[load balancer](#load-balancer) in the other region too.
 
@@ -317,7 +319,7 @@ YAML
 :  @@snip [deployment.yml](/samples/replicated/shopping-cart-service-scala/kubernetes/deployment.yml) { }
 
 
-Build the image and deploy in the same way as described previously.
+Build the image in `replicated-shopping-cart-service` directory and deploy in the same way as described previously.
 
 Scala
 :  ```

build.sbt

@@ -253,7 +253,9 @@ lazy val docs = project
         "canonical.base_url" -> "https://doc.akka.io/docs/akka-projection/current",
         "github.base_url" -> "https://github.com/akka/akka-projection",
         "akka.version" -> Dependencies.Versions.akka,
-        "akka.r2dbc.version" -> Dependencies.Versions.akkaPersistenceR2dbc),
+        "akka.r2dbc.version" -> Dependencies.Versions.akkaPersistenceR2dbc,
+        "extref.akka-distributed-cluster.base_url" -> s"https://doc.akka.io/docs/akka-distributed-cluster/${Dependencies.AkkaProjectionVersionInDocs}/%s",
+        "extref.akka-edge.base_url" -> s"https://doc.akka.io/docs/akka-edge/${Dependencies.AkkaProjectionVersionInDocs}/%s"),
     commonParadoxProperties,
     paradoxGroups := Map("Language" -> Seq("Java", "Scala")),
     paradoxRoots := List("index.html", "getting-started/event-generator-app.html"),

docs/src/main/paradox/grpc-replicated-event-sourcing-transport.md

@@ -211,10 +211,7 @@ filters on both sides. That is not handled automatically.
 
 ## Sample projects
 
-Source code and build files for complete sample projects can be found in the `akka/akka-projection` GitHub repository.
-
-* [Replicated shopping cart service in Scala](https://github.com/akka/akka-projection/tree/main/samples/replicated/shopping-cart-service-scala)
-* [Replicated shopping cart service in Java](https://github.com/akka/akka-projection/tree/main/samples/replicated/shopping-cart-service-java)
+Source code and build files for complete sample projects can be found in the @extref:[Akka Distributed Cluster Guide](akka-distributed-cluster:guide/3-active-active.html).
 
 ## Security
 

docs/src/main/paradox/grpc.md

@@ -379,17 +379,7 @@ Application level deduplication of idempotency may be needed if the Projection c
 
 ## Sample projects
 
-Source code and build files for complete sample projects can be found in `akka/akka-projection` GitHub repository. 
-
-Java:
-
-* [Producer service: shopping-cart-service-java](https://github.com/akka/akka-projection/tree/main/samples/grpc/shopping-cart-service-java)
-* [Consumer service: shopping-analytics-service-java](https://github.com/akka/akka-projection/tree/main/samples/grpc/shopping-analytics-service-java)
-
-Scala:
-
-* [Producer service: shopping-cart-service-scala](https://github.com/akka/akka-projection/tree/main/samples/grpc/shopping-cart-service-scala)
-* [Consumer service: shopping-analytics-service-scala](https://github.com/akka/akka-projection/tree/main/samples/grpc/shopping-analytics-service-scala)
+Source code and build files for complete sample projects can be found in the @extref:[Akka Distributed Cluster Guide](akka-distributed-cluster:guide.html) and @extref:[Akka Edge Guide](akka-edge:guide.html).
 
 ## Security
 
@@ -477,3 +467,4 @@ consumer2 {
 ```
 
 The `GrpcReadJournal` plugin id is then `consumer1` and `consumer2` instead of the default `akka.projection.grpc.consumer`.
+

scripts/prepare-downloads.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+
+set -e
+
+declare -r samples_sources="${PWD}/samples"
+declare -r akka_edge_docs_attachments="${PWD}/akka-edge-docs/src/main/paradox/attachments"
+declare -r akka_distributed_cluster_docs_attachments="${PWD}/akka-distributed-cluster-docs/src/main/paradox/attachments"
+declare -r target_temporal_attachments="${PWD}/target/akka-edge-docs/_attachments"
+
+declare -r temporal_folder="${PWD}/target/zips"
+
+function sed_command() {
+   local platform="$(uname -s | tr '[:upper:]' '[:lower:]')"
+
+   if [ "${platform}" != "darwin" ]; then
+      echo "sed"
+   else
+      # using gnu-sed on Mac
+      echo "gsed"
+   fi
+}
+
+## Remove the tags used by Paradox snippets from the codebase in the current folder
+function removeTags() {
+   ## remove tags from code
+   find . -type f -print0 | xargs -0 $(sed_command) -i "s/\/\/ #//g"
+}
+
+
+## Cleanup the temporal folder from previous executions
+function prepareTemporalFolder() {
+   rm -rf ${temporal_folder}
+   mkdir -p ${temporal_folder}
+}
+
+## Copy a folder with some code into the temporal folder. The 
+## copied folder will be renamed to the folder name we want the 
+## user to see when unzipping the file.
+##   source_name -> folder in `examples`
+##   target_name ->  folder name the user should see (must not use a numeric prefix of a laguage suffix)
+function fetchProject() {
+   source_name=$1
+   target_name=$2
+   echo "Fetching content from [$1] to [$2]"
+   cp -a ${source_name} ${temporal_folder}/${target_name}
+   rm -rf ${temporal_folder}/${target_name}/target
+}
+
+## Zip the contents in $temporal_folder and create the 
+## attachment file (aka, the zip file on the appropriate location)
+function zipAndAttach() {
+   zip_name=$1
+   temporal_attachments=$2
+   echo "Preparing zip $1"
+   pushd ${temporal_folder}
+   removeTags
+   zip --quiet -r ${zip_name} *
+   cp ${zip_name} ${temporal_attachments}
+   echo "Prepared attachment at ${zip_name}"
+   popd
+}
+
+mkdir -p ${akka_edge_docs_attachments}
+mkdir -p ${akka_distributed_cluster_docs_attachments}
+mkdir -p ${target_temporal_attachments}
+
+## akka-distributed-cluster-docs Scala zip files
+prepareTemporalFolder
+fetchProject ${samples_sources}/grpc/shopping-cart-service-scala shopping-cart-service
+fetchProject ${samples_sources}/grpc/shopping-analytics-service-scala shopping-analytics-service
+zipAndAttach ${akka_distributed_cluster_docs_attachments}/shopping-scala.zip ${target_temporal_attachments}
+
+prepareTemporalFolder
+fetchProject ${samples_sources}/replicated/shopping-cart-service-scala replicated-shopping-cart-service
+zipAndAttach ${akka_distributed_cluster_docs_attachments}/replicated-shopping-scala.zip ${target_temporal_attachments}
+
+## akka-distributed-cluster-docs Java zip files
+prepareTemporalFolder
+fetchProject ${samples_sources}/grpc/shopping-cart-service-java shopping-cart-service
+fetchProject ${samples_sources}/grpc/shopping-analytics-service-java shopping-analytics-service
+zipAndAttach ${akka_distributed_cluster_docs_attachments}/shopping-java.zip ${target_temporal_attachments}
+
+prepareTemporalFolder
+fetchProject ${samples_sources}/replicated/shopping-cart-service-java replicated-shopping-cart-service
+zipAndAttach ${akka_distributed_cluster_docs_attachments}/replicated-shopping-java.zip ${target_temporal_attachments}
+
+## akka-edge-docs Scala zip files
+prepareTemporalFolder
+fetchProject ${samples_sources}/grpc/local-drone-control-scala local-drone-control
+fetchProject ${samples_sources}/grpc/restaurant-drone-deliveries-service-scala restaurant-drone-deliveries-service
+zipAndAttach ${akka_edge_docs_attachments}/drone-scala.zip ${target_temporal_attachments}
+
+## akka-edge-docs Java zip files
+prepareTemporalFolder
+fetchProject ${samples_sources}/grpc/local-drone-control-java local-drone-control
+fetchProject ${samples_sources}/grpc/restaurant-drone-deliveries-service-java restaurant-drone-deliveries-service
+zipAndAttach ${akka_edge_docs_attachments}/drone-java.zip ${target_temporal_attachments}