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/camel/CustomRoute.scala

@@ -0,0 +1,63 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+
+package docs.camel
+
+import akka.camel.CamelMessage
+import akka.actor.Status.Failure
+
+import language.existentials
+
+object CustomRoute {
+  object Sample1 {
+    //#CustomRoute
+    import akka.actor.{ Props, ActorSystem, Actor, ActorRef }
+    import akka.camel.{ CamelMessage, CamelExtension }
+    import org.apache.camel.builder.RouteBuilder
+    import akka.camel._
+    class Responder extends Actor {
+      def receive = {
+        case msg: CamelMessage ⇒
+          sender ! (msg.mapBody {
+            body: String ⇒ "received %s" format body
+          })
+      }
+    }
+
+    class CustomRouteBuilder(system: ActorSystem, responder: ActorRef) extends RouteBuilder {
+      def configure {
+        from("jetty:http://localhost:8877/camel/custom").to(responder)
+      }
+    }
+    val system = ActorSystem("some-system")
+    val camel = CamelExtension(system)
+    val responder = system.actorOf(Props[Responder], name = "TestResponder")
+    camel.context.addRoutes(new CustomRouteBuilder(system, responder))
+    //#CustomRoute
+
+  }
+  object Sample2 {
+    //#ErrorThrowingConsumer
+    import akka.camel.Consumer
+
+    import org.apache.camel.builder.Builder
+    import org.apache.camel.model.RouteDefinition
+
+    class ErrorThrowingConsumer(override val endpointUri: String) extends Consumer {
+      def receive = {
+        case msg: CamelMessage ⇒ throw new Exception("error: %s" format msg.body)
+      }
+      override def onRouteDefinition(rd: RouteDefinition) = {
+        // Catch any exception and handle it by returning the exception message as response
+        rd.onException(classOf[Exception]).handled(true).transform(Builder.exceptionMessage).end
+      }
+
+      final override def preRestart(reason: Throwable, message: Option[Any]) {
+        sender ! Failure(reason)
+      }
+    }
+    //#ErrorThrowingConsumer
+  }
+
+}