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/general/code/docs/config/ConfigDocSpec.scala

@@ -0,0 +1,33 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.config
+
+import org.scalatest.WordSpec
+import org.scalatest.matchers.MustMatchers
+
+//#imports
+import akka.actor.ActorSystem
+import com.typesafe.config.ConfigFactory
+//#imports
+
+class ConfigDocSpec extends WordSpec with MustMatchers {
+
+  "programmatically configure ActorSystem" in {
+    //#custom-config
+    val customConf = ConfigFactory.parseString("""
+      akka.actor.deployment {
+        /my-service {
+          router = round-robin
+          nr-of-instances = 3
+        }
+      }
+      """)
+    // ConfigFactory.load sandwiches customConfig between default reference
+    // config and default overrides, and then resolves it.
+    val system = ActorSystem("MySystem", ConfigFactory.load(customConf))
+    //#custom-config
+
+    system.shutdown()
+  }
+}