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/code/docs/agent/AgentDocTest.java

@@ -0,0 +1,111 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.agent;
+
+import static org.junit.Assert.*;
+
+import scala.concurrent.ExecutionContext;
+import org.junit.AfterClass;
+import org.junit.BeforeClass;
+import org.junit.Test;
+import akka.testkit.AkkaSpec;
+
+//#import-system
+import akka.actor.ActorSystem;
+//#import-system
+
+//#import-agent
+import akka.agent.Agent;
+//#import-agent
+
+//#import-function
+import akka.japi.Function;
+//#import-function
+
+//#import-timeout
+import akka.util.Timeout;
+import static java.util.concurrent.TimeUnit.SECONDS;
+//#import-timeout
+
+public class AgentDocTest {
+
+  private static ActorSystem testSystem;
+  private static ExecutionContext ec;
+
+  @BeforeClass
+  public static void beforeAll() {
+    testSystem = ActorSystem.create("AgentDocTest", AkkaSpec.testConf());
+    ec = testSystem.dispatcher();
+  }
+
+  @AfterClass
+  public static void afterAll() {
+    testSystem.shutdown();
+    testSystem = null;
+  }
+
+  @Test
+  public void createAndClose() {
+        //#create
+    ActorSystem system = ActorSystem.create("app");
+
+    Agent<Integer> agent = new Agent<Integer>(5, system);
+    //#create
+
+    //#close
+    agent.close();
+    //#close
+
+    system.shutdown();
+  }
+
+  @Test
+  public void sendAndSendOffAndReadAwait() {
+    Agent<Integer> agent = new Agent<Integer>(5, testSystem);
+
+    //#send
+    // send a value
+    agent.send(7);
+
+    // send a function
+    agent.send(new Function<Integer, Integer>() {
+      public Integer apply(Integer i) {
+        return i * 2;
+      }
+    });
+    //#send
+
+    Function<Integer, Integer> longRunningOrBlockingFunction = new Function<Integer, Integer>() {
+      public Integer apply(Integer i) {
+        return i * 1;
+      }
+    };
+
+    //#send-off
+    // sendOff a function
+    agent.sendOff(longRunningOrBlockingFunction, ec);
+    //#send-off
+
+    //#read-await
+    Integer result = agent.await(new Timeout(5, SECONDS));
+    //#read-await
+
+    assertEquals(result, new Integer(14));
+
+    agent.close();
+  }
+
+  @Test
+  public void readWithGet() {
+    Agent<Integer> agent = new Agent<Integer>(5, testSystem);
+
+    //#read-get
+    Integer result = agent.get();
+    //#read-get
+
+    assertEquals(result, new Integer(5));
+
+    agent.close();
+  }
+}