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/java/extending-akka.rst

@@ -0,0 +1,88 @@
+.. _extending-akka-java:
+
+########################
+ Akka Extensions (Java)
+########################
+
+
+If you want to add features to Akka, there is a very elegant, but powerful mechanism for doing so.
+It's called Akka Extensions and is comprised of 2 basic components: an ``Extension`` and an ``ExtensionId``.
+
+Extensions will only be loaded once per ``ActorSystem``, which will be managed by Akka.
+You can choose to have your Extension loaded on-demand or at ``ActorSystem`` creation time through the Akka configuration.
+Details on how to make that happens are below, in the "Loading from Configuration" section.
+
+.. warning::
+
+    Since an extension is a way to hook into Akka itself, the implementor of the extension needs to
+    ensure the thread safety of his/her extension.
+
+
+Building an Extension
+=====================
+
+So let's create a sample extension that just lets us count the number of times something has happened.
+
+First, we define what our ``Extension`` should do:
+
+.. includecode:: code/docs/extension/ExtensionDocTestBase.java
+   :include: imports,extension
+
+Then we need to create an ``ExtensionId`` for our extension so we can grab ahold of it.
+
+.. includecode:: code/docs/extension/ExtensionDocTestBase.java
+   :include: imports,extensionid
+
+Wicked! Now all we need to do is to actually use it:
+
+.. includecode:: code/docs/extension/ExtensionDocTestBase.java
+   :include: extension-usage
+
+Or from inside of an Akka Actor:
+
+.. includecode:: code/docs/extension/ExtensionDocTestBase.java
+   :include: extension-usage-actor
+
+That's all there is to it!
+
+Loading from Configuration
+==========================
+
+To be able to load extensions from your Akka configuration you must add FQCNs of implementations of either ``ExtensionId`` or ``ExtensionIdProvider``
+in the "akka.extensions" section of the config you provide to your ``ActorSystem``.
+
+::
+
+    akka {
+      extensions = ["docs.extension.ExtensionDocTestBase.CountExtension"]
+    }
+
+Applicability
+=============
+
+The sky is the limit!
+By the way, did you know that Akka's ``Typed Actors``, ``Serialization`` and other features are implemented as Akka Extensions?
+
+.. _extending-akka-java.settings:
+
+Application specific settings
+-----------------------------
+
+The :ref:`configuration` can be used for application specific settings. A good practice is to place those settings in an Extension.
+
+Sample configuration:
+
+.. includecode:: ../scala/code/docs/extension/SettingsExtensionDocSpec.scala
+   :include: config
+
+The ``Extension``:
+
+.. includecode:: code/docs/extension/SettingsExtensionDocTestBase.java
+   :include: imports,extension,extensionid
+
+
+Use it:
+
+.. includecode:: code/docs/extension/SettingsExtensionDocTestBase.java
+   :include: extension-usage-actor
+