Merge pull request akka#179 from 2m/wip-local-doc-conf-2m

Add Local config to build docs with local api docs

CONTRIBUTING.md

@@ -36,6 +36,8 @@ Documentation should be written in two forms:
 1. API documentation in the form of scaladoc/javadoc comments on the Scala and Java user API.
 2. Guide documentation in [docs](docs/) subproject using [Paradox](https://github.com/lightbend/paradox) documentation tool. This documentation should give a short introduction of how a given connector should be used.
 
+Run `sbt docs/local:paradox` to generate reference docs while developing. Generated documentation can be found in the `./docs/target/paradox/site/local` directory.
+
 ## External Dependencies
 
 All the external runtime dependencies for the project, including transitive dependencies, must have an open source license that is equal to, or compatible with, [Apache 2](http://www.apache.org/licenses/LICENSE-2.0).

build.sbt

@@ -1,7 +1,7 @@
 lazy val alpakka = project
   .in(file("."))
   .enablePlugins(PublishUnidoc)
-  .aggregate(amqp, cassandra, dynamodb, docs, files, ftp, hbase, jms, mqtt, s3, simpleCodecs, sqs, sse)
+  .aggregate(amqp, cassandra, dynamodb, files, ftp, hbase, jms, mqtt, s3, simpleCodecs, sqs, sse)
 
 lazy val amqp = project
   .enablePlugins(AutomateHeaderPlugin)
@@ -92,19 +92,33 @@ lazy val sse = project
     Dependencies.Sse
   )
 
+val Local = config("local")
+val defaultParadoxSettings: Seq[Setting[_]] = Seq(
+  paradoxTheme := Some(builtinParadoxTheme("generic")),
+  paradoxProperties ++= Map(
+    "version" -> version.value,
+    "scala.binaryVersion" -> scalaBinaryVersion.value,
+    "extref.akka-docs.base_url" -> s"http://doc.akka.io/docs/akka/${Dependencies.AkkaVersion}/%s.html",
+    "extref.java-api.base_url" -> "https://docs.oracle.com/javase/8/docs/api/index.html?%s.html",
+    "extref.paho-api.base_url" -> "https://www.eclipse.org/paho/files/javadoc/index.html?%s.html",
+    "scaladoc.akka.base_url" -> s"http://doc.akka.io/api/akka/${Dependencies.AkkaVersion}",
+    "scaladoc.akka.stream.alpakka.base_url" -> s"http://developer.lightbend.com/docs/api/alpakka/${version.value}"
+  ),
+  sourceDirectory := baseDirectory.value / "src" / "main"
+)
+
 lazy val docs = project
   .enablePlugins(ParadoxPlugin, NoPublish)
   .disablePlugins(BintrayPlugin)
   .settings(
     name := "Alpakka",
-    paradoxTheme := Some(builtinParadoxTheme("generic")),
-    paradoxProperties ++= Map(
-      "version" -> version.value,
-      "scala.binaryVersion" -> scalaBinaryVersion.value,
-      "extref.akka-docs.base_url" -> s"http://doc.akka.io/docs/akka/${Dependencies.AkkaVersion}/%s.html",
-      "extref.java-api.base_url" -> "https://docs.oracle.com/javase/8/docs/api/index.html?%s.html",
-      "extref.paho-api.base_url" -> "https://www.eclipse.org/paho/files/javadoc/index.html?%s.html",
-      "scaladoc.akka.base_url" -> s"http://doc.akka.io/api/akka/${Dependencies.AkkaVersion}",
-      "scaladoc.akka.stream.alpakka.base_url" -> s"http://developer.lightbend.com/docs/api/alpakka/${version.value}"
+    inConfig(Compile)(defaultParadoxSettings),
+    ParadoxPlugin.paradoxSettings(Local),
+    inConfig(Local)(defaultParadoxSettings),
+    paradoxProperties in Local ++= Map(
+      // point API doc links to locally generated API docs
+      "scaladoc.akka.stream.alpakka.base_url" -> rebase(
+        (baseDirectory in alpakka).value, "../../../../../"
+      )((sbtunidoc.Plugin.UnidocKeys.unidoc in alpakka in Compile).value.head).get
     )
   )

docs/src/main/paradox/jms.md

@@ -8,7 +8,7 @@ sbt
 :   @@@vars
     ```scala
     libraryDependencies += "com.lightbend.akka" %% "akka-stream-alpakka-jms" % "$version$"
-    libraryDependencies += "javax.jms" % "jms" % "1.1"      
+    libraryDependencies += "javax.jms" % "jms" % "1.1"
     ```
     @@@
 
@@ -42,7 +42,7 @@ Gradle
 
 ### Sending messages to JMS server
 
-First define a jms `ConnectionFactory` depending on the implementation you're using. Here we're using Active MQ. 
+First define a jms `ConnectionFactory` depending on the implementation you're using. Here we're using Active MQ.
 
 Scala
 : @@snip (../../../../jms/src/test/scala/akka/stream/alpakka/jms/scaladsl/JmsConnectorsSpec.scala) { #connection-factory }
@@ -51,7 +51,7 @@ Java
 : @@snip (../../../../jms/src/test/java/akka/stream/alpakka/jms/javadsl/JmsConnectorsTest.java) { #connection-factory }
 
 
-Create a sink, that accepts and forwards @scaladoc[String](`String`)s to the JMS server.
+Create a sink, that accepts and forwards @extref[String](java-api:java.lang.String)s to the JMS server.
 
 Scala
 : @@snip (../../../../jms/src/test/scala/akka/stream/alpakka/jms/scaladsl/JmsConnectorsSpec.scala) { #create-sink }

project/plugins.sbt

@@ -1,7 +1,7 @@
 addSbtPlugin("de.heikoseeberger"                 % "sbt-header"       % "1.6.0")
 addSbtPlugin("com.geirsson"                      % "sbt-scalafmt"     % "0.4.10")
 addSbtPlugin("com.dwijnand"                      % "sbt-dynver"       % "1.1.1")
-addSbtPlugin("com.lightbend.paradox"             % "sbt-paradox"      % "0.2.5")
+addSbtPlugin("com.lightbend.paradox"             % "sbt-paradox"      % "0.2.9")
 addSbtPlugin("com.eed3si9n"                      % "sbt-unidoc"       % "0.3.3")
 addSbtPlugin("com.thoughtworks.sbt-api-mappings" % "sbt-api-mappings" % "1.0.0")
 addSbtPlugin("me.lessis"                         % "bintray-sbt"      % "0.3.0-8-g6d0c3f8")