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/ConfigDoc.java

@@ -0,0 +1,33 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.config;
+
+import akka.actor.ActorSystem;
+import com.typesafe.config.*;
+
+public class ConfigDoc {
+  public ActorSystem createConfiguredSystem() {
+    //#java-custom-config
+    // make a Config with just your special setting
+    Config myConfig =
+      ConfigFactory.parseString("something=somethingElse");
+    // load the normal config stack (system props,
+    // then application.conf, then reference.conf)
+    Config regularConfig =
+      ConfigFactory.load();
+    // override regular stack with myConfig
+    Config combined =
+      myConfig.withFallback(regularConfig);
+    // put the result in between the overrides
+    // (system props) and defaults again
+    Config complete =
+      ConfigFactory.load(combined);
+    // create ActorSystem
+    ActorSystem system =
+      ActorSystem.create("myname", complete);
+    //#java-custom-config
+    return system;
+  }
+}
+

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()
+  }
+}