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/camel/sample/http/HttpConsumer.java

@@ -0,0 +1,23 @@
+package docs.camel.sample.http;
+
+import akka.actor.ActorRef;
+import akka.camel.javaapi.UntypedConsumerActor;
+
+//#HttpExample
+public class HttpConsumer extends UntypedConsumerActor{
+
+  private ActorRef producer;
+
+  public HttpConsumer(ActorRef producer){
+    this.producer = producer;
+  }
+
+  public String getEndpointUri() {
+    return "jetty:http://0.0.0.0:8875/";
+  }
+
+  public void onReceive(Object message) {
+    producer.forward(message, getContext());
+  }
+}
+//#HttpExample

akka-docs/rst/java/code/docs/camel/sample/http/HttpProducer.java

@@ -0,0 +1,38 @@
+package docs.camel.sample.http;
+
+import akka.actor.ActorRef;
+import akka.camel.CamelMessage;
+import akka.camel.javaapi.UntypedProducerActor;
+import org.apache.camel.Exchange;
+
+import java.util.HashSet;
+import java.util.Set;
+
+//#HttpExample
+public class HttpProducer extends UntypedProducerActor{
+  private ActorRef transformer;
+
+  public HttpProducer(ActorRef transformer) {
+    this.transformer = transformer;
+  }
+
+  public String getEndpointUri() {
+    return "jetty://http://akka.io/?bridgeEndpoint=true";
+  }
+
+  @Override
+  public Object onTransformOutgoingMessage(Object message) {
+    if (message instanceof CamelMessage) {
+      CamelMessage camelMessage = (CamelMessage) message;
+      Set<String> httpPath = new HashSet<String>();
+      httpPath.add(Exchange.HTTP_PATH);
+      return camelMessage.withHeaders(camelMessage.getHeaders(httpPath));
+    } else return super.onTransformOutgoingMessage(message);
+  }
+
+  @Override
+  public void onRouteResponse(Object message) {
+    transformer.forward(message, getContext());
+  }
+}
+//#HttpExample

akka-docs/rst/java/code/docs/camel/sample/http/HttpSample.java

@@ -0,0 +1,26 @@
+package docs.camel.sample.http;
+
+import akka.actor.*;
+
+public class HttpSample {
+  public static void main(String[] args) {
+    //#HttpExample
+    // Create the actors. this can be done in a Boot class so you can
+    // run the example in the MicroKernel. just add the below three lines to your boot class.
+    ActorSystem system = ActorSystem.create("some-system");
+    final ActorRef httpTransformer = system.actorOf(new Props(HttpTransformer.class));
+
+    final ActorRef httpProducer = system.actorOf(new Props(new UntypedActorFactory(){
+      public Actor create() {
+        return new HttpProducer(httpTransformer);
+      }
+    }));
+
+    ActorRef httpConsumer = system.actorOf(new Props(new UntypedActorFactory(){
+      public Actor create() {
+        return new HttpConsumer(httpProducer);
+      }
+    }));
+    //#HttpExample
+  }
+}

akka-docs/rst/java/code/docs/camel/sample/http/HttpTransformer.java

@@ -0,0 +1,26 @@
+package docs.camel.sample.http;
+
+import akka.actor.Status;
+import akka.actor.UntypedActor;
+import akka.camel.CamelMessage;
+import akka.japi.Function;
+
+//#HttpExample
+public class HttpTransformer extends UntypedActor{
+  public void onReceive(Object message) {
+    if (message instanceof CamelMessage) {
+      CamelMessage camelMessage = (CamelMessage) message;
+      CamelMessage replacedMessage = camelMessage.mapBody(new Function<Object, String>(){
+        public String apply(Object body) {
+          String text = new String((byte[])body);
+          return text.replaceAll("Akka ", "AKKA ");
+        }
+      });
+      getSender().tell(replacedMessage, getSelf());
+    } else if (message instanceof Status.Failure) {
+      getSender().tell(message, getSelf());
+    } else
+      unhandled(message);
+  }
+}
+//#HttpExample

akka-docs/rst/java/code/docs/camel/sample/quartz/MyQuartzActor.java

@@ -0,0 +1,20 @@
+package docs.camel.sample.quartz;
+//#QuartzExample
+import akka.camel.CamelMessage;
+import akka.camel.javaapi.UntypedConsumerActor;
+
+public class MyQuartzActor extends UntypedConsumerActor{
+  public String getEndpointUri() {
+    return "quartz://example?cron=0/2+*+*+*+*+?";
+  }
+
+  public void onReceive(Object message) {
+    if (message instanceof CamelMessage) {
+      CamelMessage camelMessage = (CamelMessage) message;
+      String body = camelMessage.getBodyAs(String.class, getCamelContext());
+      System.out.println(String.format("==============> received %s ", body));
+    } else
+      unhandled(message);
+  }
+}
+//#QuartzExample

akka-docs/rst/java/code/docs/camel/sample/quartz/QuartzSample.java

@@ -0,0 +1,12 @@
+package docs.camel.sample.quartz;
+//#QuartzExample
+import akka.actor.ActorSystem;
+import akka.actor.Props;
+
+public class QuartzSample {
+  public static void main(String[] args) {
+    ActorSystem system = ActorSystem.create("my-quartz-system");
+    system.actorOf(new Props(MyQuartzActor.class));
+  }
+}
+//#QuartzExample

akka-docs/rst/java/code/docs/camel/sample/route/Consumer3.java

@@ -0,0 +1,27 @@
+package docs.camel.sample.route;
+
+//#CustomRouteExample
+import akka.actor.ActorRef;
+import akka.camel.CamelMessage;
+import akka.camel.javaapi.UntypedConsumerActor;
+
+public class Consumer3 extends UntypedConsumerActor{
+  private ActorRef transformer;
+
+  public Consumer3(ActorRef transformer){
+    this.transformer = transformer;
+  }
+
+  public String getEndpointUri() {
+    return "jetty:http://0.0.0.0:8877/camel/welcome";
+  }
+
+  public void onReceive(Object message) {
+    if (message instanceof CamelMessage) {
+      CamelMessage camelMessage = (CamelMessage) message;
+      transformer.forward(camelMessage.getBodyAs(String.class, getCamelContext()),getContext());
+    } else
+      unhandled(message);
+  }
+}
+//#CustomRouteExample

akka-docs/rst/java/code/docs/camel/sample/route/CustomRouteBuilder.java

@@ -0,0 +1,17 @@
+package docs.camel.sample.route;
+
+//#CustomRouteExample
+import org.apache.camel.Exchange;
+import org.apache.camel.Processor;
+import org.apache.camel.builder.RouteBuilder;
+
+public class CustomRouteBuilder extends RouteBuilder{
+  public void configure() throws Exception {
+    from("direct:welcome").process(new Processor(){
+      public void process(Exchange exchange) throws Exception {
+        exchange.getOut().setBody(String.format("Welcome %s",exchange.getIn().getBody()));
+      }
+    });
+  }
+}
+//#CustomRouteExample

akka-docs/rst/java/code/docs/camel/sample/route/CustomRouteSample.java

@@ -0,0 +1,31 @@
+package docs.camel.sample.route;
+
+import akka.actor.*;
+import akka.camel.CamelExtension;
+
+public class CustomRouteSample {
+  public static void main(String[] args) {
+    try {
+      //#CustomRouteExample
+      // the below lines can be added to a Boot class, so that you can run the example from a MicroKernel
+      ActorSystem system = ActorSystem.create("some-system");
+      final ActorRef producer = system.actorOf(new Props(Producer1.class));
+      final ActorRef mediator = system.actorOf(new Props(new UntypedActorFactory() {
+        public Actor create() {
+          return new Transformer(producer);
+
+        }
+      }));
+      ActorRef consumer = system.actorOf(new Props(new UntypedActorFactory() {
+        public Actor create() {
+          return new Consumer3(mediator);
+
+        }
+      }));
+      CamelExtension.get(system).context().addRoutes(new CustomRouteBuilder());
+      //#CustomRouteExample
+    } catch (Exception e) {
+      e.printStackTrace();
+    }
+  }
+}

akka-docs/rst/java/code/docs/camel/sample/route/Producer1.java

@@ -0,0 +1,10 @@
+package docs.camel.sample.route;
+//#CustomRouteExample
+import akka.camel.javaapi.UntypedProducerActor;
+
+public class Producer1 extends UntypedProducerActor{
+  public String getEndpointUri() {
+    return "direct:welcome";
+  }
+}
+//#CustomRouteExample

akka-docs/rst/java/code/docs/camel/sample/route/Transformer.java

@@ -0,0 +1,29 @@
+package docs.camel.sample.route;
+//#CustomRouteExample
+import akka.actor.ActorRef;
+import akka.actor.UntypedActor;
+import akka.camel.CamelMessage;
+import akka.japi.Function;
+
+public class Transformer extends UntypedActor {
+  private ActorRef producer;
+
+  public Transformer(ActorRef producer) {
+    this.producer = producer;
+  }
+
+  public void onReceive(Object message) {
+    if (message instanceof CamelMessage) {
+      // example: transform message body "foo" to "- foo -" and forward result to producer
+      CamelMessage camelMessage = (CamelMessage) message;
+      CamelMessage transformedMessage = camelMessage.mapBody(new Function<String, String>(){
+        public String apply(String body) {
+          return String.format("- %s -",body);
+        }
+      });
+      producer.forward(transformedMessage, getContext());
+    } else
+      unhandled(message);
+  }
+}
+//#CustomRouteExample