add some comments, fix experimental status of cluster

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

@@ -20,7 +20,7 @@ The Akka cluster is a separate jar file. Make sure that you have the following d
 
 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@/>`_.
+`<http://repo.typesafe.com/typesafe/snapshots/com/typesafe/akka/akka-cluster-experimental_@binVersion@/>`_.
 We recommend against using ``SNAPSHOT`` in order to obtain stable builds.
 
 A Simple Cluster Example

project/AkkaBuild.scala

@@ -469,6 +469,8 @@ object AkkaBuild extends Build {
     testOptions in Test += Tests.Argument("-oDF")
   )
 
+  // customization of sphinx @<key>@ replacements, add to all sphinx-using projects
+  // add additional replacements here
   lazy val sphinxReplacements = Seq(
     sphinxVars <<= (scalaVersion, version) { (s, v) =>
       val BinVer = """(\d+\.\d+)\.\d+""".r
@@ -489,7 +491,7 @@ object AkkaBuild extends Build {
           })
       )
     },
-    sphinxExts += "py"
+    sphinxExts += "py" // needed for transforming conf.py
   )
 
   lazy val formatSettings = ScalariformPlugin.scalariformSettings ++ Seq(

project/Sphinx.scala

@@ -67,7 +67,12 @@ object Sphinx {
           def dst(f: File) = temp.toPath.resolve(docs.toPath.relativize(f.toPath)).toFile
           def filter(f: File) = filterExt contains f.getName.reverse.takeWhile('.' !=).reverse
           val Replacer = """@(\w+)@""".r
+          /*
+           * First Step: bring filtered source tree in sync with orig source tree
+           */
+          // delete files which were removed
           in.removed foreach (f => IO delete dst(f))
+          // transform the other files by applying the replacement map for @<key>@ tokens
           (in.modified ++ (in.checked -- out.checked)).toSeq.sorted foreach { f =>
             if (f.isFile)
               if (filter(f)) {
@@ -84,10 +89,14 @@ object Sphinx {
                   }
                 }
               } else {
+                // do not transform PNGs et al
                 s.log.debug("Changed documentation source (copying): " + f)
                 IO.copyFile(f, dst(f))
               }
           }
+          /*
+           * Second Step: invoke sphinx-build
+           */
           val tagList = if (tags.isEmpty) "" else tags.mkString(" (", ", ", ")")
           val desc = "%s%s" format (builder, tagList)
           s.log.info("Building Sphinx %s documentation..." format desc)
@@ -101,7 +110,7 @@ object Sphinx {
           s.log.info("Sphinx %s documentation created: %s" format (desc, target))
           temp.descendentsExcept("*", "").get.toSet
         }
-        val toplevel = docs * ("*" - ".*" - "_sphinx" - "_build" - "disabled" - "target")
+        val toplevel = docs * ("*" - "disabled")
         val inputs = toplevel.descendentsExcept("*", "").get.toSet
         cached(inputs)
         target