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/remoting/RemoteDeploymentDocSpec.scala

@@ -0,0 +1,52 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.remoting
+
+import akka.actor.{ ExtendedActorSystem, ActorSystem, Actor, ActorRef }
+import akka.testkit.{ AkkaSpec, ImplicitSender }
+//#import
+import akka.actor.{ Props, Deploy, Address, AddressFromURIString }
+import akka.remote.RemoteScope
+//#import
+
+object RemoteDeploymentDocSpec {
+
+  class Echo extends Actor {
+    def receive = {
+      case x ⇒ sender ! self
+    }
+  }
+
+}
+
+class RemoteDeploymentDocSpec extends AkkaSpec("""
+    akka.actor.provider = "akka.remote.RemoteActorRefProvider"
+    akka.remote.netty.port = 0
+""") with ImplicitSender {
+
+  import RemoteDeploymentDocSpec._
+
+  val other = ActorSystem("remote", system.settings.config)
+  val address = other.asInstanceOf[ExtendedActorSystem].provider.getExternalAddressFor(Address("akka", "s", "host", 1)).get
+
+  override def atTermination() { other.shutdown() }
+
+  "demonstrate programmatic deployment" in {
+    //#deploy
+    val ref = system.actorOf(Props[Echo].withDeploy(Deploy(scope = RemoteScope(address))))
+    //#deploy
+    ref.path.address must be(address)
+    ref ! "test"
+    expectMsgType[ActorRef].path.address must be(address)
+  }
+
+  "demonstrate address extractor" in {
+    //#make-address
+    val one = AddressFromURIString("akka://sys@host:1234")
+    val two = Address("akka", "sys", "host", 1234) // this gives the same
+    //#make-address
+    one must be === two
+  }
+
+}