Operators: Add example for groupBy (#29875)

akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupBy.md

@@ -28,6 +28,14 @@ memory issues. Elements belonging to those keys are drained directly and not sen
 
 @@@
 
+## Example
+
+Scala
+:   @@snip [GroupBy.scala](/akka-docs/src/test/scala/docs/stream/operators/sourceorflow/GroupBy.scala) { #groupBy }
+
+Java
+:   @@snip [GroupBy.java](/akka-docs/src/test/java/jdocs/stream/operators/SourceOrFlow.java) { #groupBy }
+
 ## Reactive Streams semantics
 
 @@@div { .callout }

akka-docs/src/test/java/jdocs/stream/operators/SourceOrFlow.java

@@ -477,6 +477,18 @@ class SourceOrFlow {
     // #watch
   }
 
+  void groupByExample() {
+    // #groupBy
+    Source.range(1, 10)
+        .groupBy(2, i -> i % 2 == 0) // create two sub-streams with odd and even numbers
+        .reduce(Integer::sum) // for each sub-stream, sum its elements
+        .mergeSubstreams() // merge back into a stream
+        .runForeach(System.out::println, system);
+    // 25
+    // 30
+    // #groupBy
+  }
+
   static CompletionStage<Done> completionTimeoutExample() {
     // #completionTimeout
     Source<Integer, NotUsed> source = Source.range(1, 100000).map(number -> number * number);

akka-docs/src/test/scala/docs/stream/operators/sourceorflow/GroupBy.scala

@@ -0,0 +1,25 @@
+/*
+ * Copyright (C) 2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package docs.stream.operators.sourceorflow
+
+import akka.actor.ActorSystem
+import akka.stream.scaladsl.Source
+
+object GroupBy {
+
+  def groupBySourceExample(): Unit = {
+    implicit val system: ActorSystem = ???
+    //#groupBy
+    Source(1 to 10)
+      .groupBy(maxSubstreams = 2, _ % 2 == 0) // create two sub-streams with odd and even numbers
+      .reduce(_ + _) // for each sub-stream, sum its elements
+      .mergeSubstreams // merge back into a stream
+      .runForeach(println)
+    //25
+    //30
+    //#groupBy
+  }
+
+}