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/testkit/PlainWordSpec.scala

@@ -0,0 +1,47 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.testkit
+
+//#plain-spec
+import akka.actor.ActorSystem
+import akka.actor.Actor
+import akka.actor.Props
+import akka.testkit.TestKit
+import org.scalatest.WordSpec
+import org.scalatest.matchers.MustMatchers
+import org.scalatest.BeforeAndAfterAll
+import akka.testkit.ImplicitSender
+
+object MySpec {
+  class EchoActor extends Actor {
+    def receive = {
+      case x ⇒ sender ! x
+    }
+  }
+}
+
+//#implicit-sender
+class MySpec(_system: ActorSystem) extends TestKit(_system) with ImplicitSender
+  with WordSpec with MustMatchers with BeforeAndAfterAll {
+  //#implicit-sender
+
+  def this() = this(ActorSystem("MySpec"))
+
+  import MySpec._
+
+  override def afterAll {
+    system.shutdown()
+  }
+
+  "An Echo actor" must {
+
+    "send back messages unchanged" in {
+      val echo = system.actorOf(Props[EchoActor])
+      echo ! "hello world"
+      expectMsg("hello world")
+    }
+
+  }
+}
+//#plain-spec