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/common/code/docs/circuitbreaker/CircuitBreakerDocSpec.scala

@@ -0,0 +1,43 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+
+package docs.circuitbreaker
+
+//#imports1
+import scala.concurrent.util.duration._ // small d is important here
+import akka.pattern.CircuitBreaker
+import akka.actor.Actor
+import scala.concurrent.Future
+import akka.event.Logging
+
+//#imports1
+
+class CircuitBreakerDocSpec {}
+
+//#circuit-breaker-initialization
+class DangerousActor extends Actor {
+
+  val log = Logging(context.system, this)
+  implicit val executionContext = context.dispatcher
+  val breaker =
+    new CircuitBreaker(context.system.scheduler, 5, 10.seconds, 1.minute)
+      .onOpen(notifyMeOnOpen)
+
+  def notifyMeOnOpen =
+    log.warning("My CircuitBreaker is now open, and will not close for one minute")
+  //#circuit-breaker-initialization
+
+  //#circuit-breaker-usage
+  def dangerousCall: String = "This really isn't that dangerous of a call after all"
+
+  def receive = {
+    case "is my middle name" ⇒
+      sender ! breaker.withCircuitBreaker(Future(dangerousCall))
+    case "block for me" ⇒
+      sender ! breaker.withSyncCircuitBreaker(dangerousCall)
+  }
+  //#circuit-breaker-usage
+
+}
+

akka-docs/rst/common/code/docs/circuitbreaker/DangerousJavaActor.java

@@ -0,0 +1,83 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.circuitbreaker;
+
+//#imports1
+
+import akka.actor.UntypedActor;
+import scala.concurrent.Future;
+import akka.event.LoggingAdapter;
+import scala.concurrent.util.Duration;
+import akka.pattern.CircuitBreaker;
+import akka.event.Logging;
+
+import static akka.dispatch.Futures.future;
+
+import java.util.concurrent.Callable;
+
+//#imports1
+
+//#circuit-breaker-initialization
+public class DangerousJavaActor extends UntypedActor {
+
+    private final CircuitBreaker breaker;
+    private final LoggingAdapter log = Logging.getLogger(getContext().system(), this);
+
+    public DangerousJavaActor() {
+        this.breaker = new CircuitBreaker(
+                getContext().dispatcher(), getContext().system().scheduler(),
+                5, Duration.create(10, "s"), Duration.create(1, "m"))
+                .onOpen(new Callable<Object>() {
+                    public Object call() throws Exception {
+                        notifyMeOnOpen();
+                        return null;
+                    }
+                });
+    }
+
+    public void notifyMeOnOpen() {
+        log.warning("My CircuitBreaker is now open, and will not close for one minute");
+    }
+//#circuit-breaker-initialization
+
+    //#circuit-breaker-usage
+    public String dangerousCall() {
+        return "This really isn't that dangerous of a call after all";
+    }
+
+    @Override
+    public void onReceive(Object message) {
+        if (message instanceof String) {
+            String m = (String) message;
+            if ("is my middle name".equals(m)) {
+                final Future<String> f = future(
+                        new Callable<String>() {
+                            public String call() {
+                                return dangerousCall();
+                            }
+                        }, getContext().dispatcher());
+
+                getSender().tell(breaker
+                        .callWithCircuitBreaker(
+                                new Callable<Future<String>>() {
+                                    public Future<String> call() throws Exception {
+                                        return f;
+                                    }
+                                }), getSelf());
+            }
+            if ("block for me".equals(m)) {
+                getSender().tell(breaker
+                        .callWithSyncCircuitBreaker(
+                                new Callable<String>() {
+                                    @Override
+                                    public String call() throws Exception {
+                                        return dangerousCall();
+                                    }
+                                }), getSelf());
+            }
+        }
+    }
+//#circuit-breaker-usage
+
+}