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/extension/SettingsExtensionDocSpec.scala

@@ -0,0 +1,78 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.extension
+
+//#imports
+import akka.actor.Extension
+import akka.actor.ExtensionId
+import akka.actor.ExtensionIdProvider
+import akka.actor.ExtendedActorSystem
+import scala.concurrent.util.Duration
+import com.typesafe.config.Config
+import java.util.concurrent.TimeUnit
+
+//#imports
+
+import akka.actor.Actor
+import akka.testkit.AkkaSpec
+
+//#extension
+class SettingsImpl(config: Config) extends Extension {
+  val DbUri: String = config.getString("myapp.db.uri")
+  val CircuitBreakerTimeout: Duration = Duration(config.getMilliseconds("myapp.circuit-breaker.timeout"), TimeUnit.MILLISECONDS)
+}
+//#extension
+
+//#extensionid
+object Settings extends ExtensionId[SettingsImpl] with ExtensionIdProvider {
+
+  override def lookup = Settings
+
+  override def createExtension(system: ExtendedActorSystem) = new SettingsImpl(system.settings.config)
+}
+//#extensionid
+
+object SettingsExtensionDocSpec {
+
+  val config = """
+    //#config
+    myapp {
+      db {
+        uri = "mongodb://example1.com:27017,example2.com:27017"
+      }
+      circuit-breaker {
+        timeout = 30 seconds
+      }
+    }
+    //#config
+    """
+
+  //#extension-usage-actor
+
+  class MyActor extends Actor {
+    val settings = Settings(context.system)
+    val connection = connect(settings.DbUri, settings.CircuitBreakerTimeout)
+
+    //#extension-usage-actor
+    def receive = {
+      case someMessage ⇒
+    }
+
+    def connect(dbUri: String, circuitBreakerTimeout: Duration) = {
+      "dummy"
+    }
+  }
+
+}
+
+class SettingsExtensionDocSpec extends AkkaSpec(SettingsExtensionDocSpec.config) {
+
+  "demonstrate how to create application specific settings extension in Scala" in {
+    //#extension-usage
+    val dbUri = Settings(system).DbUri
+    val circuitBreakerTimeout = Settings(system).CircuitBreakerTimeout
+    //#extension-usage
+  }
+
+}