add preprocessor for RST docs, see #2461 and #2431

The idea is to filter the sources, replacing @<var>@ occurrences with
the mapping for <var> (which is currently hard-coded). @@ -> @. In order
to make this work, I had to move the doc sources one directory down
(into akka-docs/rst) so that the filtered result could be in a sibling
directory so that relative links (to _sphinx plugins or real code) would
continue to work.

While I was at it I also changed it so that WARNINGs and ERRORs are not
swallowed into the debug dump anymore but printed at [warn] level
(minimum).

One piece of fallout is that the (online) html build is now run after
the normal one, not in parallel.

akka-docs/rst/scala/code/docs/routing/ConsistentHashingRouterDocSpec.scala

@@ -0,0 +1,73 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.routing
+
+import akka.testkit.AkkaSpec
+import akka.testkit.ImplicitSender
+
+object ConsistentHashingRouterDocSpec {
+
+  //#cache-actor
+  import akka.actor.Actor
+  import akka.routing.ConsistentHashingRouter.ConsistentHashable
+
+  class Cache extends Actor {
+    var cache = Map.empty[String, String]
+
+    def receive = {
+      case Entry(key, value) ⇒ cache += (key -> value)
+      case Get(key)          ⇒ sender ! cache.get(key)
+      case Evict(key)        ⇒ cache -= key
+    }
+  }
+
+  case class Evict(key: String)
+
+  case class Get(key: String) extends ConsistentHashable {
+    override def consistentHashKey: Any = key
+  }
+
+  case class Entry(key: String, value: String)
+  //#cache-actor
+
+}
+
+class ConsistentHashingRouterDocSpec extends AkkaSpec with ImplicitSender {
+
+  import ConsistentHashingRouterDocSpec._
+
+  "demonstrate usage of ConsistentHashableRouter" in {
+
+    //#consistent-hashing-router
+    import akka.actor.Props
+    import akka.routing.ConsistentHashingRouter
+    import akka.routing.ConsistentHashingRouter.ConsistentHashMapping
+    import akka.routing.ConsistentHashingRouter.ConsistentHashableEnvelope
+
+    def hashMapping: ConsistentHashMapping = {
+      case Evict(key) ⇒ key
+    }
+
+    val cache = system.actorOf(Props[Cache].withRouter(ConsistentHashingRouter(10,
+      hashMapping = hashMapping)), name = "cache")
+
+    cache ! ConsistentHashableEnvelope(
+      message = Entry("hello", "HELLO"), hashKey = "hello")
+    cache ! ConsistentHashableEnvelope(
+      message = Entry("hi", "HI"), hashKey = "hi")
+
+    cache ! Get("hello")
+    expectMsg(Some("HELLO"))
+
+    cache ! Get("hi")
+    expectMsg(Some("HI"))
+
+    cache ! Evict("hi")
+    cache ! Get("hi")
+    expectMsg(None)
+
+    //#consistent-hashing-router
+  }
+
+}

akka-docs/rst/scala/code/docs/routing/RouterDocSpec.scala

@@ -0,0 +1,29 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.routing
+
+import RouterDocSpec.MyActor
+import akka.testkit.AkkaSpec
+import akka.routing.RoundRobinRouter
+import akka.actor.{ ActorRef, Props, Actor }
+
+object RouterDocSpec {
+  class MyActor extends Actor {
+    def receive = {
+      case _ ⇒
+    }
+  }
+}
+
+class RouterDocSpec extends AkkaSpec {
+
+  import RouterDocSpec._
+
+  //#dispatchers
+  val router: ActorRef = system.actorOf(Props[MyActor]
+    .withRouter(RoundRobinRouter(5, routerDispatcher = "router")) // “head” will run on "router" dispatcher
+    .withDispatcher("workers")) // MyActor workers will run on "workers" dispatcher
+  //#dispatchers
+
+}

akka-docs/rst/scala/code/docs/routing/RouterTypeExample.scala

@@ -0,0 +1,94 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.routing
+
+import language.postfixOps
+
+import akka.routing.{ ScatterGatherFirstCompletedRouter, BroadcastRouter, RandomRouter, RoundRobinRouter }
+import annotation.tailrec
+import akka.actor.{ Props, Actor }
+import scala.concurrent.util.duration._
+import akka.util.Timeout
+import scala.concurrent.Await
+import akka.pattern.ask
+import akka.routing.SmallestMailboxRouter
+
+case class FibonacciNumber(nbr: Int)
+
+//#printlnActor
+class PrintlnActor extends Actor {
+  def receive = {
+    case msg ⇒
+      println("Received message '%s' in actor %s".format(msg, self.path.name))
+  }
+}
+
+//#printlnActor
+
+//#fibonacciActor
+class FibonacciActor extends Actor {
+  def receive = {
+    case FibonacciNumber(nbr) ⇒ sender ! fibonacci(nbr)
+  }
+
+  private def fibonacci(n: Int): Int = {
+    @tailrec
+    def fib(n: Int, b: Int, a: Int): Int = n match {
+      case 0 ⇒ a
+      case _ ⇒ fib(n - 1, a + b, b)
+    }
+
+    fib(n, 1, 0)
+  }
+}
+
+//#fibonacciActor
+
+//#parentActor
+class ParentActor extends Actor {
+  def receive = {
+    case "rrr" ⇒
+      //#roundRobinRouter
+      val roundRobinRouter =
+        context.actorOf(Props[PrintlnActor].withRouter(RoundRobinRouter(5)), "router")
+      1 to 10 foreach {
+        i ⇒ roundRobinRouter ! i
+      }
+    //#roundRobinRouter
+    case "rr" ⇒
+      //#randomRouter
+      val randomRouter =
+        context.actorOf(Props[PrintlnActor].withRouter(RandomRouter(5)), "router")
+      1 to 10 foreach {
+        i ⇒ randomRouter ! i
+      }
+    //#randomRouter
+    case "smr" ⇒
+      //#smallestMailboxRouter
+      val smallestMailboxRouter =
+        context.actorOf(Props[PrintlnActor].withRouter(SmallestMailboxRouter(5)), "router")
+      1 to 10 foreach {
+        i ⇒ smallestMailboxRouter ! i
+      }
+    //#smallestMailboxRouter
+    case "br" ⇒
+      //#broadcastRouter
+      val broadcastRouter =
+        context.actorOf(Props[PrintlnActor].withRouter(BroadcastRouter(5)), "router")
+      broadcastRouter ! "this is a broadcast message"
+    //#broadcastRouter
+    case "sgfcr" ⇒
+      //#scatterGatherFirstCompletedRouter
+      val scatterGatherFirstCompletedRouter = context.actorOf(
+        Props[FibonacciActor].withRouter(ScatterGatherFirstCompletedRouter(
+          nrOfInstances = 5, within = 2 seconds)), "router")
+      implicit val timeout = Timeout(5 seconds)
+      val futureResult = scatterGatherFirstCompletedRouter ? FibonacciNumber(10)
+      val result = Await.result(futureResult, timeout.duration)
+      //#scatterGatherFirstCompletedRouter
+      println("The result of calculating Fibonacci for 10 is %d".format(result))
+  }
+}
+
+//#parentActor

akka-docs/rst/scala/code/docs/routing/RouterViaConfigDocSpec.scala

@@ -0,0 +1,158 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.routing
+
+import akka.actor.{ Actor, Props, ActorSystem, ActorLogging }
+import com.typesafe.config.ConfigFactory
+import akka.routing.FromConfig
+import akka.routing.ConsistentHashingRouter.ConsistentHashable
+import akka.testkit.AkkaSpec
+import akka.testkit.ImplicitSender
+
+object RouterWithConfigDocSpec {
+
+  val config = ConfigFactory.parseString("""
+
+    //#config-round-robin
+    akka.actor.deployment {
+      /myrouter1 {
+        router = round-robin
+        nr-of-instances = 5
+      }
+    }
+    //#config-round-robin
+
+    //#config-resize
+    akka.actor.deployment {
+      /myrouter2 {
+        router = round-robin
+        resizer {
+          lower-bound = 2
+          upper-bound = 15
+        }
+      }
+    }
+    //#config-resize
+
+    //#config-random
+    akka.actor.deployment {
+      /myrouter3 {
+        router = random
+        nr-of-instances = 5
+      }
+    }
+    //#config-random
+
+    //#config-smallest-mailbox
+    akka.actor.deployment {
+      /myrouter4 {
+        router = smallest-mailbox
+        nr-of-instances = 5
+      }
+    }
+    //#config-smallest-mailbox
+
+    //#config-broadcast
+    akka.actor.deployment {
+      /myrouter5 {
+        router = broadcast
+        nr-of-instances = 5
+      }
+    }
+    //#config-broadcast
+
+    //#config-scatter-gather
+    akka.actor.deployment {
+      /myrouter6 {
+        router = scatter-gather
+        nr-of-instances = 5
+        within = 10 seconds
+      }
+    }
+    //#config-scatter-gather
+
+    //#config-consistent-hashing
+    akka.actor.deployment {
+      /myrouter7 {
+        router = consistent-hashing
+        nr-of-instances = 5
+        virtual-nodes-factor = 10
+      }
+    }
+    //#config-consistent-hashing
+
+    """)
+
+  case class Message(nbr: Int) extends ConsistentHashable {
+    override def consistentHashKey = nbr
+  }
+
+  class ExampleActor extends Actor with ActorLogging {
+    def receive = {
+      case Message(nbr) ⇒
+        log.debug("Received %s in router %s".format(nbr, self.path.name))
+        sender ! nbr
+    }
+  }
+
+}
+
+class RouterWithConfigDocSpec extends AkkaSpec(RouterWithConfigDocSpec.config) with ImplicitSender {
+
+  import RouterWithConfigDocSpec._
+
+  "demonstrate configured round-robin router" in {
+    //#configurableRouting
+    val router = system.actorOf(Props[ExampleActor].withRouter(FromConfig()),
+      "myrouter1")
+    //#configurableRouting
+    1 to 10 foreach { i ⇒ router ! Message(i) }
+    receiveN(10)
+  }
+
+  "demonstrate configured random router" in {
+    val router = system.actorOf(Props[ExampleActor].withRouter(FromConfig()),
+      "myrouter3")
+    1 to 10 foreach { i ⇒ router ! Message(i) }
+    receiveN(10)
+  }
+
+  "demonstrate configured smallest-mailbox router" in {
+    val router = system.actorOf(Props[ExampleActor].withRouter(FromConfig()),
+      "myrouter4")
+    1 to 10 foreach { i ⇒ router ! Message(i) }
+    receiveN(10)
+  }
+
+  "demonstrate configured broadcast router" in {
+    val router = system.actorOf(Props[ExampleActor].withRouter(FromConfig()),
+      "myrouter5")
+    1 to 10 foreach { i ⇒ router ! Message(i) }
+    receiveN(5 * 10)
+  }
+
+  "demonstrate configured scatter-gather router" in {
+    val router = system.actorOf(Props[ExampleActor].withRouter(FromConfig()),
+      "myrouter6")
+    1 to 10 foreach { i ⇒ router ! Message(i) }
+    receiveN(10)
+  }
+
+  "demonstrate configured consistent-hashing router" in {
+    val router = system.actorOf(Props[ExampleActor].withRouter(FromConfig()),
+      "myrouter7")
+    1 to 10 foreach { i ⇒ router ! Message(i) }
+    receiveN(10)
+  }
+
+  "demonstrate configured round-robin router with resizer" in {
+    //#configurableRoutingWithResizer
+    val router = system.actorOf(Props[ExampleActor].withRouter(FromConfig()),
+      "myrouter2")
+    //#configurableRoutingWithResizer
+    1 to 10 foreach { i ⇒ router ! Message(i) }
+    receiveN(10)
+  }
+
+}

akka-docs/rst/scala/code/docs/routing/RouterViaConfigExample.scala

@@ -0,0 +1,52 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.routing
+
+import akka.actor.{ Actor, Props, ActorSystem }
+import com.typesafe.config.ConfigFactory
+import akka.routing.FromConfig
+
+case class Message(nbr: Int)
+
+class ExampleActor extends Actor {
+  def receive = {
+    case Message(nbr) ⇒ println("Received %s in router %s".format(nbr, self.path.name))
+  }
+}
+
+object RouterWithConfigExample extends App {
+  val config = ConfigFactory.parseString("""
+    //#config
+    akka.actor.deployment {
+      /router {
+        router = round-robin
+        nr-of-instances = 5
+      }
+    }
+    //#config
+    //#config-resize
+    akka.actor.deployment {
+      /router2 {
+        router = round-robin
+        resizer {
+          lower-bound = 2
+          upper-bound = 15
+        }
+      }
+    }
+    //#config-resize
+      """)
+  val system = ActorSystem("Example", config)
+  //#configurableRouting
+  val router = system.actorOf(Props[ExampleActor].withRouter(FromConfig()),
+    "router")
+  //#configurableRouting
+  1 to 10 foreach { i ⇒ router ! Message(i) }
+
+  //#configurableRoutingWithResizer
+  val router2 = system.actorOf(Props[ExampleActor].withRouter(FromConfig()),
+    "router2")
+  //#configurableRoutingWithResizer
+  1 to 10 foreach { i ⇒ router2 ! Message(i) }
+}

akka-docs/rst/scala/code/docs/routing/RouterViaProgramExample.scala

@@ -0,0 +1,53 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.routing
+
+import akka.routing.RoundRobinRouter
+import akka.actor.{ ActorRef, Props, Actor, ActorSystem }
+import akka.routing.DefaultResizer
+import akka.remote.routing.RemoteRouterConfig
+
+case class Message1(nbr: Int)
+
+class ExampleActor1 extends Actor {
+  def receive = {
+    case Message1(nbr) ⇒ println("Received %s in router %s".format(nbr, self.path.name))
+  }
+}
+
+object RoutingProgrammaticallyExample extends App {
+  val system = ActorSystem("RPE")
+  //#programmaticRoutingNrOfInstances
+  val router1 = system.actorOf(Props[ExampleActor1].withRouter(
+    RoundRobinRouter(nrOfInstances = 5)))
+  //#programmaticRoutingNrOfInstances
+  1 to 6 foreach { i ⇒ router1 ! Message1(i) }
+
+  //#programmaticRoutingRoutees
+  val actor1 = system.actorOf(Props[ExampleActor1])
+  val actor2 = system.actorOf(Props[ExampleActor1])
+  val actor3 = system.actorOf(Props[ExampleActor1])
+  val routees = Vector[ActorRef](actor1, actor2, actor3)
+  val router2 = system.actorOf(Props().withRouter(
+    RoundRobinRouter(routees = routees)))
+  //#programmaticRoutingRoutees
+  1 to 6 foreach { i ⇒ router2 ! Message1(i) }
+
+  //#programmaticRoutingWithResizer
+  val resizer = DefaultResizer(lowerBound = 2, upperBound = 15)
+  val router3 = system.actorOf(Props[ExampleActor1].withRouter(
+    RoundRobinRouter(resizer = Some(resizer))))
+  //#programmaticRoutingWithResizer
+  1 to 6 foreach { i ⇒ router3 ! Message1(i) }
+
+  //#remoteRoutees
+  import akka.actor.{ Address, AddressFromURIString }
+  val addresses = Seq(
+    Address("akka", "remotesys", "otherhost", 1234),
+    AddressFromURIString("akka://othersys@anotherhost:1234"))
+  val routerRemote = system.actorOf(Props[ExampleActor1].withRouter(
+    RemoteRouterConfig(RoundRobinRouter(5), addresses)))
+  //#remoteRoutees
+
+}