docs: more cleaner instructions to run the examples

README.md

@@ -2,16 +2,16 @@
 
 ## Goals of the project
 
-> In the realm of asynchronous programming, the Scala ecosystem offers a set of solid monads constructs to tackle complex task functionally with elegance and efficiency, like [Monix Tasks](https://monix.io/docs/current/eval/task.html) and [Cats Effect](https://typelevel.org/cats-effect/).
->
-> However, we are assisting to the increase in adoption of continuation and coroutines in modern runtimes, either exploiting some kind of fibers support, like the project Loom with Virtual Threads, or via code generation, like Kotlin Coroutines.
->
-> The goal of this project is to delve into this field through the lens of direct style, developing few examples (not too complex) leveraging the new *strawman* library [Scala Gears](https://github.com/lampepfl/gears), comparing it with Kotlin's Coroutines and the current implementation of monadic Futures, seeking to analyze aspects such as:
->
-> - ergonomics of the two styles (which one results more thoughtful and/or verbose);
-> - which of the two approaches has a real advantage in adoption;
-> - pros and cons of the two styles;
-> - any limitations and difficulties encountered in using them.
+In the realm of asynchronous programming, the Scala ecosystem offers a set of solid monads constructs to tackle complex task functionally with elegance and efficiency, like [Monix Tasks](https://monix.io/docs/current/eval/task.html) and [Cats Effect](https://typelevel.org/cats-effect/).
+
+However, we are assisting to the increase in adoption of continuation and coroutines in modern runtimes, either exploiting some kind of fibers support, like the project Loom with Virtual Threads, or via code generation, like Kotlin Coroutines.
+
+The goal of this project is to delve into this field through the lens of direct style, developing few examples (not too complex) leveraging the new *strawman* library [Scala Gears](https://github.com/lampepfl/gears), comparing it with Kotlin's Coroutines and the current implementation of monadic Futures, seeking to analyze aspects such as:
+
+- ergonomics of the two styles (which one results more thoughtful and/or verbose);
+- which of the two approaches has a real advantage in adoption;
+- pros and cons of the two styles;
+- any limitations and difficulties encountered in using them.
 
 ## Overview
 
@@ -65,6 +65,4 @@ Generally speaking, the runnable examples can be run by simply executing the `ru
 ./gradlew :analyzer-direct:run
 ```
 
-Detailed instructions can be found in the `README` file of the submodule and in the [documentation](https://tassiluca.github.io/direct-style-experiments/).
-
-The documentation can be found [here](https://tassiluca.github.io/direct-style-experiments/).
+Detailed instructions can be found in the `README` file of each submodule and in the [documentation](https://tassiluca.github.io/direct-style-experiments/).

docs/content/docs/02-basics.md

@@ -45,6 +45,12 @@ The example is organized into Gradle submodules:
 - `blog-ws-direct` contains the direct version using Scala Gears;
 - `blog-ws-direct-kt` contains the direct version using Kotlin Coroutines.
 
+For this example just the tests are provided. You can explore them in the `test` folders and run via Gradle using the name of the submodule:
+
+```
+./gradlew :blog-ws-<monadic | direct | direct-kt>:test
+```
+
 ### Structure
 
 The domain is modeled using abstract data types in a common `PostsModel` trait:

docs/content/docs/03-channels.md

@@ -213,6 +213,28 @@ listing their information along with all their contributors as soon as they are
 
 ![expected result](../../res/img/analyzer-e2e.png)
 
+---
+
+To start the application:
+
+```bash
+./gradlew analyzer-<direct | direct-kt | monadic>:run
+```
+
+{{< hint warning >}}
+
+In order to run the application you need to place inside the `analyzer-commons` directory a `.env` file containing [your personal GitHub access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), like:
+
+```env
+GH_TOKEN=....
+```
+
+or having set an environment variable named `GH_TOKEN`.
+
+{{< /hint >}}
+
+---
+
 The example is structured in two different packages: `lib` and `client`. The former contains the logic of the library, while the latter contains the application (client code).
 As usual, it has been implemented using monadic `Future`s, as well as using Scala Gears and Kotlin Coroutines.
 
@@ -440,28 +462,6 @@ override def analyze(organizationName: String)(
 3. we start the analysis in a separate `Future` (i.e. thread): this allows you to start the analysis as soon as a repository is fetched by the channel, preventing starting the analysis of the next repository only when the previous one is finished;
 4. once all the repositories are retrieved, i.e. the `foreach` terminates, we wait for the completion of all the started `Future`s. Indeed, when the `foreach` terminates, we have the guarantee that all started futures have been started, but not yet completed!
 
----
-
-To start the application:
-
-```bash
-./gradlew analyzer-direct:run
-```
-
-{{< hint warning >}}
-
-In order to run the application you need to place inside the `analyzer-commons` directory a `.env` file containing [your personal GitHub access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), like:
-
-```env
-GH_TOKEN=....
-```
-
-or having set an environment variable named `GH_TOKEN`.
-
-{{< /hint >}}
-
----
-
 ### Kotlin Coroutines version
 
 [[The sources are available inside the `analyzer-direct-kt` submodule](https://github.com/tassiLuca/direct-style-experiments/tree/master/analyzer-direct-kt/src/main/kotlin/io/github/tassiLuca/analyzer).]

docs/content/docs/04-rears.md

@@ -474,7 +474,7 @@ To produce a testable version of this example, a simulated source of sensor data
 The example is runnable via:
 
 ```bash
-./gradlew smart-hub-direct:run
+./gradlew smart-hub-<direct | direct-kt>:run
 ```
 
 Three panels should pop up, one for each sensor type, and a dashboard showing the state of the system.