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.

.gitignore

@@ -49,7 +49,8 @@ multiverse.log
 .eprj
 .*.swp
 akka-docs/_build/
-akka-docs/epilog_rst
+akka-docs/rst_html
+akka-docs/rst_latex
 *.pyc
 akka-docs/exts/
 _akka_cluster/

akka-docs/rst/cluster/cluster-usage.rst

@@ -16,10 +16,12 @@ The Akka cluster is a separate jar file. Make sure that you have the following d
 
 .. parsed-literal::
 
-  "com.typesafe.akka" %% "akka-cluster" % "2.1-SNAPSHOT"
+  "com.typesafe.akka" %% "akka-cluster" % "@version@" @crossString@
 
-If you are using the latest nightly build you should pick a timestamped Akka version from `<http://repo.typesafe.com/typesafe/snapshots/com/typesafe/akka/>`_. Don't use ``SNAPSHOT``. Note that the Scala version |scalaVersion| 
-is part of the artifactId.
+If you are using the latest nightly build you should pick a timestamped Akka
+version from
+`<http://repo.typesafe.com/typesafe/snapshots/com/typesafe/akka/akka-cluster_@binVersion@/>`_.
+We recommend against using ``SNAPSHOT`` in order to obtain stable builds.
 
 A Simple Cluster Example
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -32,7 +34,7 @@ Try it out:
 1. Add the following ``application.conf`` in your project, place it in ``src/main/resources``:
 
 
-.. literalinclude:: ../../akka-samples/akka-sample-cluster/src/main/resources/application.conf
+.. literalinclude:: ../../../akka-samples/akka-sample-cluster/src/main/resources/application.conf
    :language: none
 
 To enable cluster capabilities in your Akka project you should, at a minimum, add the :ref:`remoting-scala`
@@ -47,7 +49,7 @@ ip-addresses or host names of the machines in ``application.conf`` instead of ``
 
 2. Add the following main program to your project, place it in ``src/main/scala``:
 
-.. literalinclude:: ../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/simple/SimpleClusterApp.scala   
+.. literalinclude:: ../../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/simple/SimpleClusterApp.scala   
    :language: scala
 
 
@@ -167,15 +169,15 @@ added or removed to the cluster dynamically.
 
 In this example the following imports are used:
 
-.. includecode:: ../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/transformation/TransformationSample.scala#imports
+.. includecode:: ../../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/transformation/TransformationSample.scala#imports
 
 Messages:
 
-.. includecode:: ../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/transformation/TransformationSample.scala#messages
+.. includecode:: ../../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/transformation/TransformationSample.scala#messages
 
 The backend worker that performs the transformation job:
 
-.. includecode:: ../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/transformation/TransformationSample.scala#backend
+.. includecode:: ../../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/transformation/TransformationSample.scala#backend
 
 Note that the ``TransformationBackend`` actor subscribes to cluster events to detect new,
 potential, frontend nodes, and send them a registration message so that they know
@@ -183,7 +185,7 @@ that they can use the backend worker.
 
 The frontend that receives user jobs and delegates to one of the registered backend workers:
 
-.. includecode:: ../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/transformation/TransformationSample.scala#frontend
+.. includecode:: ../../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/transformation/TransformationSample.scala#frontend
 
 Note that the ``TransformationFrontend`` actor watch the registered backend
 to be able to remove it from its list of availble backend workers.
@@ -224,7 +226,7 @@ routees are added to the router, according to the configuration.
 When using a router with routees looked up on the cluster member nodes, i.e. the routees
 are already running, the configuration for a router looks like this:
 
-.. includecode:: ../../akka-samples/akka-sample-cluster/src/multi-jvm/scala/sample/cluster/stats/StatsSampleSpec.scala#router-lookup-config
+.. includecode:: ../../../akka-samples/akka-sample-cluster/src/multi-jvm/scala/sample/cluster/stats/StatsSampleSpec.scala#router-lookup-config
 
 It's the relative actor path defined in ``routees-path`` that identify what actor to lookup.
 
@@ -234,12 +236,12 @@ added to the router when nodes join the cluster.
 
 The same type of router could also have been defined in code:
 
-.. includecode:: ../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/stats/StatsSample.scala#router-lookup-in-code
+.. includecode:: ../../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/stats/StatsSample.scala#router-lookup-in-code
 
 When using a router with routees created and deployed on the cluster member nodes
 the configuration for a router looks like this:
 
-.. includecode:: ../../akka-samples/akka-sample-cluster/src/multi-jvm/scala/sample/cluster/stats/StatsSampleSingleMasterSpec.scala#router-deploy-config
+.. includecode:: ../../../akka-samples/akka-sample-cluster/src/multi-jvm/scala/sample/cluster/stats/StatsSampleSingleMasterSpec.scala#router-deploy-config
 
 
 ``nr-of-instances`` defines total number of routees in the cluster, but the number of routees 
@@ -249,7 +251,7 @@ the cluster.
 
 The same type of router could also have been defined in code:
 
-.. includecode:: ../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/stats/StatsSample.scala#router-deploy-in-code
+.. includecode:: ../../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/stats/StatsSample.scala#router-deploy-in-code
 
 See :ref:`cluster_configuration` section for further descriptions of the settings.
 
@@ -267,19 +269,19 @@ the average number of characters per word when all results have been collected.
 
 In this example we use the following imports:
 
-.. includecode:: ../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/stats/StatsSample.scala#imports
+.. includecode:: ../../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/stats/StatsSample.scala#imports
 
 Messages:
 
-.. includecode:: ../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/stats/StatsSample.scala#messages
+.. includecode:: ../../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/stats/StatsSample.scala#messages
 
 The worker that counts number of characters in each word:
 
-.. includecode:: ../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/stats/StatsSample.scala#worker
+.. includecode:: ../../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/stats/StatsSample.scala#worker
 
 The service that receives text from users and splits it up into words, delegates to workers and aggregates:
 
-.. includecode:: ../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/stats/StatsSample.scala#service
+.. includecode:: ../../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/stats/StatsSample.scala#service
 
 
 Note, nothing cluster specific so far, just plain actors.
@@ -290,7 +292,7 @@ or with create and deploy of routees. Remember, routees are the workers in this
 We start with the router setup with lookup of routees. All nodes start ``StatsService`` and
 ``StatsWorker`` actors and the router is configured with ``routees-path``:
 
-.. includecode:: ../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/stats/StatsSample.scala#start-router-lookup
+.. includecode:: ../../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/stats/StatsSample.scala#start-router-lookup
 
 This means that user requests can be sent to ``StatsService`` on any node and it will use 
 ``StatsWorker`` on all nodes. There can only be one worker per node, but that worker could easily 
@@ -312,7 +314,7 @@ The above setup is nice for this example, but we will also take a look at how to
 a single master node that creates and deploys workers. To keep track of a single
 master we need one additional actor:
 
-.. includecode:: ../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/stats/StatsSample.scala#facade
+.. includecode:: ../../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/stats/StatsSample.scala#facade
 
 The ``StatsFacade`` receives text from users and delegates to the current ``StatsService``, the single
 master. It listens to cluster events to create or lookup the ``StatsService`` depending on if
@@ -322,7 +324,7 @@ i.e. it can change when new nodes join or when current leader leaves.
 
 All nodes start ``StatsFacade`` and the router is now configured like this:
 
-.. includecode:: ../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/stats/StatsSample.scala#start-router-deploy
+.. includecode:: ../../../akka-samples/akka-sample-cluster/src/main/scala/sample/cluster/stats/StatsSample.scala#start-router-deploy
 
 
 This example is included in ``akka-samples/akka-sample-cluster``
@@ -407,7 +409,7 @@ There are several configuration properties for the cluster. We refer to the foll
 reference file for more information:
 
 
-.. literalinclude:: ../../akka-cluster/src/main/resources/reference.conf
+.. literalinclude:: ../../../akka-cluster/src/main/resources/reference.conf
    :language: none
 
 Cluster Scheduler

akka-docs/rst/conf.py

@@ -7,7 +7,7 @@ import sys, os
 
 # -- General configuration -----------------------------------------------------
 
-sys.path.append(os.path.abspath('_sphinx/exts'))
+sys.path.append(os.path.abspath('../_sphinx/exts'))
 extensions = ['sphinx.ext.todo', 'includecode']
 
 templates_path = ['_templates']
@@ -17,29 +17,25 @@ exclude_patterns = ['_build', 'pending', 'disabled']
 
 project = u'Akka'
 copyright = u'2011, Typesafe Inc'
-version = '2.1-SNAPSHOT'
-release = '2.1-SNAPSHOT'
+version = '@version@'
+release = '@version@'
 
 pygments_style = 'simple'
 highlight_language = 'scala'
 add_function_parentheses = False
 show_authors = True
 
-f = open('epilog_rst', 'U')
-rst_epilog = "\n" + f.read()
-f.close()
-
 # -- Options for HTML output ---------------------------------------------------
 
 html_theme = 'akka'
-html_theme_path = ['_sphinx/themes']
-html_favicon = '_sphinx/static/favicon.ico'
+html_theme_path = ['../_sphinx/themes']
+html_favicon = '../_sphinx/static/favicon.ico'
 
 html_title = 'Akka Documentation'
-html_logo = '_sphinx/static/logo.png'
+html_logo = '../_sphinx/static/logo.png'
 #html_favicon = None
 
-html_static_path = ['_sphinx/static']
+html_static_path = ['../_sphinx/static']
 
 html_last_updated_fmt = '%b %d, %Y'
 #html_sidebars = {}
@@ -63,7 +59,7 @@ epub_language = "en"
 epub_publisher = epub_author
 epub_identifier = "http://doc.akka.io/docs/akka/snapshot/"
 epub_scheme = "URL"
-epub_cover = ("_sphinx/static/akka.png", "")
+epub_cover = ("../_sphinx/static/akka.png", "")
 
 # -- Options for LaTeX output --------------------------------------------------
 

akka-docs/rst/dev/multi-jvm-testing.rst

@@ -49,8 +49,8 @@ multi-JVM testing (Simplified for clarity):
 
     lazy val buildSettings = Defaults.defaultSettings ++ SbtMultiJvm.multiJvmSettings ++ Seq(
       organization := "com.typesafe.akka",
-      version      := "2.1-SNAPSHOT",
-      scalaVersion := "|scalaVersion|",
+      version      := "@version@",
+      scalaVersion := "@scalaVersion@",
       crossPaths   := false
     )
 

akka-docs/rst/general/configuration.rst

@@ -142,7 +142,7 @@ before or after using them to construct an actor system:
 
 .. parsed-literal::
 
-  Welcome to Scala version |scalaVersion| (Java HotSpot(TM) 64-Bit Server VM, Java 1.6.0_27).
+  Welcome to Scala version @scalaVersion@ (Java HotSpot(TM) 64-Bit Server VM, Java 1.6.0_27).
   Type in expressions to have them evaluated.
   Type :help for more information.
 
@@ -337,41 +337,41 @@ Each Akka module has a reference configuration file with the default values.
 akka-actor
 ~~~~~~~~~~
 
-.. literalinclude:: ../../akka-actor/src/main/resources/reference.conf
+.. literalinclude:: ../../../akka-actor/src/main/resources/reference.conf
    :language: none
 
 akka-remote
 ~~~~~~~~~~~
 
-.. literalinclude:: ../../akka-remote/src/main/resources/reference.conf
+.. literalinclude:: ../../../akka-remote/src/main/resources/reference.conf
    :language: none
 
 akka-testkit
 ~~~~~~~~~~~~
 
-.. literalinclude:: ../../akka-testkit/src/main/resources/reference.conf
+.. literalinclude:: ../../../akka-testkit/src/main/resources/reference.conf
    :language: none
 
 akka-transactor
 ~~~~~~~~~~~~~~~
 
-.. literalinclude:: ../../akka-transactor/src/main/resources/reference.conf
+.. literalinclude:: ../../../akka-transactor/src/main/resources/reference.conf
    :language: none
 
 akka-agent
 ~~~~~~~~~~
 
-.. literalinclude:: ../../akka-agent/src/main/resources/reference.conf
+.. literalinclude:: ../../../akka-agent/src/main/resources/reference.conf
    :language: none
 
 akka-zeromq
 ~~~~~~~~~~~
 
-.. literalinclude:: ../../akka-zeromq/src/main/resources/reference.conf
+.. literalinclude:: ../../../akka-zeromq/src/main/resources/reference.conf
    :language: none
 
 akka-file-mailbox
 ~~~~~~~~~~~~~~~~~
 
-.. literalinclude:: ../../akka-durable-mailboxes/akka-file-mailbox/src/main/resources/reference.conf
+.. literalinclude:: ../../../akka-durable-mailboxes/akka-file-mailbox/src/main/resources/reference.conf
    :language: none

akka-docs/rst/intro/getting-started.rst

@@ -29,18 +29,21 @@ Akka Maven repository.
 Modules
 -------
 
-Akka is very modular and has many JARs for containing different features.
+Akka is very modular and consists of several JARs containing different features.
 
-- ``akka-actor-2.1-SNAPSHOT.jar`` -- Classic Actors, Typed Actors, IO Actor etc.
-- ``akka-remote-2.1-SNAPSHOT.jar`` -- Remote Actors
-- ``akka-testkit-2.1-SNAPSHOT.jar`` -- Toolkit for testing Actor systems
-- ``akka-kernel-2.1-SNAPSHOT.jar`` -- Akka microkernel for running a bare-bones mini application server
-- ``akka-transactor-2.1-SNAPSHOT.jar`` -- Transactors - transactional actors, integrated with Scala STM
-- ``akka-agent-2.1-SNAPSHOT.jar`` -- Agents, integrated with Scala STM
-- ``akka-camel-2.1-SNAPSHOT.jar`` -- Apache Camel integration
-- ``akka-zeromq-2.1-SNAPSHOT.jar`` -- ZeroMQ integration
-- ``akka-slf4j-2.1-SNAPSHOT.jar`` -- SLF4J Event Handler Listener
-- ``akka-<storage-system>-mailbox-2.1-SNAPSHOT.jar`` -- Akka durable mailboxes
+- ``akka-actor`` -- Classic Actors, Typed Actors, IO Actor etc.
+- ``akka-remote`` -- Remote Actors
+- ``akka-testkit`` -- Toolkit for testing Actor systems
+- ``akka-kernel`` -- Akka microkernel for running a bare-bones mini application server
+- ``akka-transactor`` -- Transactors - transactional actors, integrated with Scala STM
+- ``akka-agent`` -- Agents, integrated with Scala STM
+- ``akka-camel`` -- Apache Camel integration
+- ``akka-zeromq`` -- ZeroMQ integration
+- ``akka-slf4j`` -- SLF4J Event Handler Listener
+- ``akka-filebased-mailbox`` -- Akka durable mailbox (find more among community projects)
+
+The filename of the actual JAR is for example ``@jarName@`` (and analog for
+the other modules).
 
 How to see the JARs dependencies of each Akka module is described in the
 :ref:`dependencies` section.
@@ -84,26 +87,16 @@ The simplest way to get started with Akka and Maven is to check out the
 `Akka/Maven template <http://typesafe.com/resources/getting-started/typesafe-stack/downloading-installing.html#template-projects-for-scala-akka-and-play>`_
 project.
 
-Summary of the essential parts for using Akka with Maven:
-
-1) Add this repository to your ``pom.xml``:
-
-.. code-block:: xml
-
-  <repository>
-    <id>typesafe</id>
-    <name>Typesafe Repository</name>
-    <url>http://repo.typesafe.com/typesafe/releases/</url>
-  </repository>
-
-2) Add the Akka dependencies. For example, here is the dependency for Akka Actor 2.1-SNAPSHOT:
+Since Akka is published to Maven Central (for versions since 2.1-M2), is it
+enough to add the Akka dependencies to the POM. For example, here is the
+dependency for akka-actor:
 
 .. code-block:: xml
 
   <dependency>
     <groupId>com.typesafe.akka</groupId>
-    <artifactId>akka-actor</artifactId>
-    <version>2.1-SNAPSHOT</version>
+    <artifactId>akka-actor_@binVersion@</artifactId>
+    <version>@version@</version>
   </dependency>
 
 **Note**: for snapshot versions both ``SNAPSHOT`` and timestamped versions are published.
@@ -128,11 +121,12 @@ SBT installation instructions on `https://github.com/harrah/xsbt/wiki/Setup <htt
 
     version := "1.0"
 
-    scalaVersion := "|scalaVersion|"
+    scalaVersion := "@scalaVersion@"
 
     resolvers += "Typesafe Repository" at "http://repo.typesafe.com/typesafe/releases/"
 
-    libraryDependencies += "com.typesafe.akka" % "akka-actor" % "2.1-SNAPSHOT"
+    libraryDependencies +=
+      "com.typesafe.akka" %% "akka-actor" % "@version@" @crossString@
 
 
 Using Akka with Eclipse
@@ -167,3 +161,4 @@ If you have questions you can get help on the `Akka Mailing List <http://groups.
 You can also ask for `commercial support <http://typesafe.com>`_.
 
 Thanks for being a part of the Akka community.
+