Add dependency snippets to relevant doc sections (#24418)

* Add dependency snippets to relevant doc sections

* Add 'Dependency' headings

Tried to consistently add them to each section introducing a module, after
the introduction but before the first code sample.

* Make Dependency sections more consistent

akka-docs/src/main/paradox/cluster-sharding.md

@@ -31,6 +31,16 @@ See @ref:[Downing](cluster-usage.md#automatic-vs-manual-downing).
 
 @@@
 
+## Dependency
+
+To use Akka Cluster Sharding, add the module to your project:
+
+@@dependency[sbt,Maven,Gradle] {
+  group="com.typesafe.akka"
+  artifact="akka-cluster-sharding_$scala.binary_version$"
+  version="$akka.version$"
+}
+
 ## An Example
 
 This is how an entity actor may look like:

akka-docs/src/main/paradox/cluster-usage.md

@@ -2,34 +2,15 @@
 
 For introduction to the Akka Cluster concepts please see @ref:[Cluster Specification](common/cluster.md).
 
-## Preparing Your Project for Clustering
+## Dependency
 
-The Akka cluster is a separate jar file. Make sure that you have the following dependency in your project:
+To use Akka Cluster, add the module to your project:
 
-sbt
+@@dependency[sbt,Maven,Gradle] {
-:   @@@vars
+  group="com.typesafe.akka"
-    ```
+  artifact="akka-cluster_$scala.binary_version$"
-    "com.typesafe.akka" %% "akka-cluster" % "$akka.version$"
+  version="$akka.version$"
-    ```
+}
-    @@@
-   
-Gradle
-:   @@@vars
-    ```
-     compile group: 'com.typesafe.akka', name: 'akka-cluster_$scala.binary_version$', version: '$akka.version$'
-    ```
-    @@@
-
-Maven
-:   @@@vars
-    ```
-    <dependency>
-      <groupId>com.typesafe.akka</groupId>
-      <artifactId>akka-cluster_$scala.binary_version$</artifactId>
-      <version>$akka.version$</version>
-    </dependency>
-    ```
-    @@@
 
 ## A Simple Cluster Example
 

akka-docs/src/main/paradox/distributed-data.md

@@ -19,6 +19,16 @@ It is eventually consistent and geared toward providing high read and write avai
 (partition tolerance), with low latency. Note that in an eventually consistent system a read may return an
 out-of-date value.
 
+## Dependency
+
+To use Akka Distributed Data, add the module to your project:
+
+@@dependency[sbt,Maven,Gradle] {
+  group="com.typesafe.akka"
+  artifact="akka-distributed-data_$scala.binary_version$"
+  version="$akka.version$"
+}
+
 ## Using the Replicator
 
 The `akka.cluster.ddata.Replicator` actor provides the API for interacting with the data.

akka-docs/src/main/paradox/persistence.md

@@ -13,64 +13,26 @@ Akka persistence is inspired by and the official replacement of the [eventsource
 concepts and architecture of [eventsourced](https://github.com/eligosource/eventsourced) but significantly differs on API and implementation level. See also
 @ref:[migration-eventsourced-2.3](project/migration-guide-eventsourced-2.3.x.md)
 
-## Dependencies
+## Dependency
 
-Akka persistence is a separate jar file. Make sure that you have the following dependency in your project:
+To use Akka Persistence, add the module to your project:
 
-sbt
+@@dependency[sbt,Maven,Gradle] {
-:   @@@vars
+  group="com.typesafe.akka"
-    ```
+  artifact="akka-persistence_$scala.binary_version$"
-    "com.typesafe.akka" %% "akka-persistence" % "$akka.version$"
+  version="$akka.version$"
-    ```
+}
-    @@@
 
-Gradle
+The Akka Persistence extension comes with few built-in persistence plugins, including
-:   @@@vars
-    ``` 
-    compile group: 'com.typesafe.akka', name: 'akka-persistence_$scala.binary_version$', version: '$akka.version$'
-    ```
-    @@@
-
-Maven
-:   @@@vars
-    ```
-    <dependency>
-      <groupId>com.typesafe.akka</groupId>
-      <artifactId>akka-persistence_$scala.binary_version$</artifactId>
-      <version>$akka.version$</version>
-    </dependency>
-    ```
-    @@@
-
-The Akka persistence extension comes with few built-in persistence plugins, including
 in-memory heap based journal, local file-system based snapshot-store and LevelDB based journal.
 
-LevelDB based plugins will require the following additional dependency declaration:
+LevelDB-based plugins will require the following additional dependency:
 
-sbt
+@@dependency[sbt,Maven,Gradle] {
-:   @@@vars
+  group="org.fusesource.leveldbjni"
-    ```
+  artifact="leveldbjni-all"
-    "org.fusesource.leveldbjni"   % "leveldbjni-all"   % "1.8"
+  version="1.8"
-    ```
+}
-    @@@
-
-Gradle
-:   @@@vars
-    ```
-    compile group: 'org.fusesource.leveldbjni', name: 'leveldbjni-all', version: '1.8' 
-    ```
-    @@@
-
-Maven
-:   @@@vars
-    ```
-    <dependency>
-      <groupId>org.fusesource.leveldbjni</groupId>
-      <artifactId>leveldbjni-all</artifactId>
-      <version>1.8</version>
-    </dependency>
-    ```
-    @@@
 
 ## Architecture
 

akka-docs/src/main/paradox/stream/stream-quickstart.md

@@ -1,7 +1,16 @@
 # Streams Quickstart Guide
 
-Create a project and add the akka-streams dependency to the build tool of your
+## Dependency
-choice.
+
+To use Akka Streams, add the module to your project:
+
+@@dependency[sbt,Maven,Gradle] {
+  group="com.typesafe.akka"
+  artifact="akka-stream_$scala.binary_version$"
+  version="$akka.version$"
+}
+
+## First steps
 
 A stream usually begins at a source, so this is also how we start an Akka
 Stream. Before we create one, we import the full complement of streaming tools:

akka-docs/src/main/paradox/stream/stream-testkit.md

@@ -13,7 +13,7 @@ flows and sinks. This makes them easily testable by wiring them up to other
 sources or sinks, or some test harnesses that `akka-testkit` or
 `akka-stream-testkit` provide.
 
-## Built in sources, sinks and combinators
+## Built-in sources, sinks and combinators
 
 Testing a custom sink can be as simple as attaching a source that emits
 elements from a predefined collection, running a constructed test flow and
@@ -93,11 +93,18 @@ provides tools specifically for writing stream tests. This module comes with
 two main components that are `TestSource` and `TestSink` which
 provide sources and sinks that materialize to probes that allow fluent API.
 
-@@@ note
+### Dependency
 
-Be sure to add the module `akka-stream-testkit` to your dependencies.
+To use Akka Stream TestKit, add the module to your project:
 
-@@@
+@@dependency[sbt,Maven,Gradle] {
+  group="com.typesafe.akka"
+  artifact="akka-stream-testkit_$scala.binary_version$"
+  version="$akka.version$"
+  scope="test"
+}
+
+### Using the TestKit
 
 A sink returned by `TestSink.probe` allows manual control over demand and
 assertions over elements coming downstream.

akka-docs/src/main/paradox/testing.md

@@ -7,9 +7,9 @@ perform tests.
 
 Akka comes with a dedicated module `akka-testkit` for supporting tests.
 
-## Dependencies 
+## Dependency
 
-Be sure to add the module `akka-testkit` to your dependencies.
+To use Akka Testkit, add the module to your project:
 
 @@dependency[sbt,Maven,Gradle] {
   group="com.typesafe.akka"

akka-docs/src/main/paradox/typed/actors.md

@@ -9,15 +9,11 @@ This module is currently marked as @ref:[may change](../common/may-change.md) in
 
 @@@
 
-### Migrating to 2.5.9
+## Dependency
-
-* `EffectfulActorContext` has been renamed to `BehaviourTestKit`
-* `Inbox` has been renamed to `TestInbox` to allign with `TestProbe`
-* Separated into modules e.g. `akka-actor-typed` `akka-persistence-typed` along with matching package names
 
 To use Akka Typed add the following dependency:
 
-@@dependency [sbt,Maven,Gradle] {
+@@dependency[sbt,Maven,Gradle] {
   group=com.typesafe.akka
   artifact=akka-actor-typed_2.12
   version=$akka.version$
@@ -358,3 +354,10 @@ address. While we cannot statically express the “current” state of an Actor,
 can express the current state of a protocol between two Actors, since that is
 just given by the last message type that was received or sent.
 
+## Migrating
+
+### Migrating to 2.5.9
+
+* `EffectfulActorContext` has been renamed to `BehaviourTestKit`
+* `Inbox` has been renamed to `TestInbox` to allign with `TestProbe`
+* Separated into modules e.g. `akka-actor-typed` `akka-persistence-typed` along with matching package names

akka-docs/src/main/paradox/typed/cluster-sharding.md

@@ -1,5 +1,8 @@
 # Cluster Sharding
 
+For an introduction to Sharding concepts see @ref:[Cluster Sharding](../cluster-sharding.md). This documentation shows how to use the typed
+Cluster Sharding API.
+
 @@@ warning
 
 This module is currently marked as @ref:[may change](../common/may-change.md) in the sense
@@ -9,17 +12,16 @@ This module is currently marked as @ref:[may change](../common/may-change.md) in
 
 @@@
 
-To use cluster sharding add the following dependency:
+## Dependency
 
-@@dependency [sbt,Maven,Gradle] {
+To use Akka Cluster Sharding, add the module to your project:
+
+@@dependency[sbt,Maven,Gradle] {
   group=com.typesafe.akka
   artifact=akka-cluster-sharding-typed_2.12
   version=$akka.version$
 }
 
-For an introduction to Sharding concepts see @ref:[Cluster Sharding](../cluster-sharding.md). This documentation shows how to use the typed
-Cluster Sharding API.
-
 ## Basic example
 
 Sharding is accessed via the `ClusterSharding` extension

akka-docs/src/main/paradox/typed/cluster-singleton.md

@@ -1,22 +1,5 @@
 # Cluster Singleton
 
-@@@ warning
-
-This module is currently marked as @ref:[may change](../common/may-change.md) in the sense
-  of being the subject of active research. This means that API or semantics can
-  change without warning or deprecation period and it is not recommended to use
-  this module in production just yet—you have been warned.
-  
-@@@
-
-To use the cluster singletons add the following dependency:
-
-@@dependency [sbt,Maven,Gradle] {
-  group=com.typesafe.akka
-  artifact=akka-cluster-typed_2.12
-  version=$akka.version$
-}
-
 For some use cases it is convenient and sometimes also mandatory to ensure that
 you have exactly one actor of a certain type running somewhere in the cluster.
 
@@ -33,7 +16,26 @@ such as single-point of bottleneck. Single-point of failure is also a relevant c
 but for some cases this feature takes care of that by making sure that another singleton
 instance will eventually be started.
 
-# Example
+@@@ warning
+
+This module is currently marked as @ref:[may change](../common/may-change.md) in the sense
+  of being the subject of active research. This means that API or semantics can
+  change without warning or deprecation period and it is not recommended to use
+  this module in production just yet—you have been warned.
+
+@@@
+
+## Dependency
+
+To use Akka Cluster Singleton, add the module to your project:
+
+@@dependency[sbt,Maven,Gradle] {
+  group=com.typesafe.akka
+  artifact=akka-cluster-typed_2.12
+  version=$akka.version$
+}
+
+## Example
 
 Any `Behavior` can be run as a singleton. E.g. a basic counter:
 

akka-docs/src/main/paradox/typed/cluster.md

@@ -1,5 +1,8 @@
 # Cluster
 
+For an introduction to Akka Cluster concepts see @ref:[Cluster Specification](../common/cluster.md). This documentation shows how to use the typed
+Cluster API.
+
 @@@ warning
 
 This module is currently marked as @ref:[may change](../common/may-change.md) in the sense
@@ -9,16 +12,19 @@ This module is currently marked as @ref:[may change](../common/may-change.md) in
 
 @@@
 
-To use the testkit add the following dependency:
+## Dependency
 
-@@dependency [sbt,Maven,Gradle] {
+To use Akka Cluster Typed, add the module to your project:
+
+@@dependency[sbt,Maven,Gradle] {
   group=com.typesafe.akka
   artifact=akka-cluster-typed_2.12
   version=$akka.version$
 }
 
-For an introduction to Akka Cluster concepts see @ref:[Cluster Specification](../common/cluster.md). This documentation shows how to use the typed
+## Examples
-Cluster API. All of the examples below assume the following imports:
+
+All of the examples below assume the following imports:
 
 Scala
 :  @@snip [BasicClusterExampleSpec.scala]($akka$/akka-cluster-typed/src/test/scala/docs/akka/cluster/typed/BasicClusterExampleSpec.scala) { #cluster-imports }

akka-docs/src/main/paradox/typed/persistence.md

@@ -1,5 +1,9 @@
 # Persistence
 
+Akka Persistence is a library for building event sourced actors. For background about how it works
+see the @ref:[untyped Akka Persistence section](../persistence.md). This documentation shows how the typed API for persistence
+works and assumes you know what is meant by `Command`, `Event` and `State`.
+
 @@@ warning
 
 This module is currently marked as @ref:[may change](../common/may-change.md) in the sense
@@ -16,19 +20,17 @@ to track progress and to contribute to the Java DSL.
 
 @@@
 
-To use typed persistence add the following dependency:
+## Dependency
 
-@@dependency [sbt,Maven,Gradle] {
+To use Akka Persistence Typed, add the module to your project:
+
+@@dependency[sbt,Maven,Gradle] {
   group=com.typesafe.akka
   artifact=akka-persistence-typed_2.11
   version=$akka.version$
 }
 
-
+## Example
-
-Akka Persistence is a library for building event sourced actors. For background about how it works
-see the @ref:[untyped Akka Persistence section](../persistence.md). This documentation shows how the typed API for persistence
-works and assumes you know what is meant by `Command`, `Event` and `State`.
 
 Let's start with a simple example. The minimum required for a `PersistentBehavior` is:
 

akka-docs/src/main/paradox/typed/testing.md

@@ -1,24 +1,5 @@
 # Testing
 
-@@@ warning
-
-This module is currently marked as @ref:[may change](../common/may-change.md) in the sense
-  of being the subject of active research. This means that API or semantics can
-  change without warning or deprecation period and it is not recommended to use
-  this module in production just yet—you have been warned.
-  
-  
-@@@
-
-To use the testkit add the following dependency:
-
-@@dependency [sbt,Maven,Gradle] {
-  group=com.typesafe.akka
-  artifact=akka-testkit-typed_2.12
-  version=$akka.version$
-  scope=test
-}
-   
 Testing can either be done asynchronously using a real `ActorSystem` or synchronously on the testing thread using the `BehaviousTestKit`.  
 
 For testing logic in a `Behavior` in isolation synchronous testing is preferred. For testing interactions between multiple
@@ -28,6 +9,26 @@ Certain `Behavior`s will be hard to test synchronously e.g. if they spawn Future
 before observing the effect you want to test. Further support for controlling the scheduler and execution context used
 will be added.
 
+@@@ warning
+
+This module is currently marked as @ref:[may change](../common/may-change.md) in the sense
+  of being the subject of active research. This means that API or semantics can
+  change without warning or deprecation period and it is not recommended to use
+  this module in production just yet—you have been warned.
+
+@@@
+
+## Dependency
+
+To use Akka TestKit Type, add the module to your project:
+
+@@dependency[sbt,Maven,Gradle] {
+  group=com.typesafe.akka
+  artifact=akka-testkit-typed_2.12
+  version=$akka.version$
+  scope=test
+}
+
 ## Synchronous behaviour testing
 
 The following demonstrates how to test: