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/java/code/docs/jrouting/RouterViaConfigExample.java

@@ -0,0 +1,58 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.jrouting;
+
+import akka.routing.FromConfig;
+import akka.actor.ActorRef;
+import akka.actor.Props;
+import akka.actor.UntypedActor;
+import akka.actor.ActorSystem;
+import com.typesafe.config.ConfigFactory;
+import com.typesafe.config.Config;
+
+public class RouterViaConfigExample {
+
+  public static class ExampleActor extends UntypedActor {
+    public void onReceive(Object msg) {
+      if (msg instanceof Message) {
+        Message message = (Message) msg;
+        System.out.println(String.format("Received %s in router %s", message.getNbr(), getSelf().path().name()));
+      } else {
+        unhandled(msg);
+      }
+    }
+
+    public static class Message {
+      private final int nbr;
+
+      public Message(int nbr) {
+        this.nbr = nbr;
+      }
+
+      public int getNbr() {
+        return nbr;
+      }
+
+    }
+  }
+
+  public static void main(String... args) {
+    Config config = ConfigFactory.parseString("akka.actor.deployment {\n" + "  /router {\n"
+        + "    router = round-robin\n" + "    nr-of-instances = 5\n" + "  }\n" + "}\n");
+    ActorSystem system = ActorSystem.create("Example", config);
+    //#configurableRouting
+    ActorRef router = system.actorOf(new Props(ExampleActor.class).withRouter(new FromConfig()), "router");
+    //#configurableRouting
+    for (int i = 1; i <= 10; i++) {
+      router.tell(new ExampleActor.Message(i), null);
+    }
+
+    //#configurableRoutingWithResizer
+    ActorRef router2 = system.actorOf(new Props(ExampleActor.class).withRouter(new FromConfig()), "router2");
+    //#configurableRoutingWithResizer
+    for (int i = 1; i <= 10; i++) {
+      router2.tell(new ExampleActor.Message(i), null);
+    }
+  }
+}