Build paradox and api docs with sbt-site

.travis.yml

@@ -31,7 +31,7 @@ jobs:
       name: "Compile all tests (with Scala 2.11)"
     - env: CMD="unidoc"
       name: "Create all API docs"
-    - env: CMD="docs/paradox"
+    - env: CMD="docs/Paradox/paradox"
       name: "Create site with Paradox"
 
     - stage: test
@@ -106,9 +106,7 @@ jobs:
 
     - stage: publish
       script: sbt -jvm-opts .jvmopts-travis +publish
-
-    - stage: techhub-ping
-      script: curl -I https://ci.lightbend.com/job/techhub-publisher/build?token=$TECH_HUB_TOKEN
+    - script: openssl aes-256-cbc -K $encrypted_bbf1dc4f2a07_key -iv $encrypted_bbf1dc4f2a07_iv -in .travis/travis_alpakka_rsa.enc -out .travis/id_rsa -d && eval "$(ssh-agent -s)" && chmod 600 .travis/id_rsa && ssh-add .travis/id_rsa && sbt -jvm-opts .jvmopts-travis docs/publishRsync
 
 stages:
   # runs on master commits and PRs
@@ -127,10 +125,6 @@ stages:
   - name: publish
     if: repo = akka/alpakka AND ( ( branch = master AND type = push ) OR tag =~ ^v )
 
-  # runs on main repo version-tagged commits
-  - name: techhub-ping
-    if: repo = akka/alpakka AND tag =~ ^v
-
 after_failure:
   - docker-compose logs
   - find . -name "*.log" -exec ./scripts/cat-log.sh {} \;

build.sbt

@@ -42,8 +42,8 @@ lazy val modules: Seq[ProjectReference] = Seq(
 
 lazy val alpakka = project
   .in(file("."))
-  .enablePlugins(PublishUnidoc)
-  .disablePlugins(MimaPlugin)
+  .enablePlugins(ScalaUnidocPlugin)
+  .disablePlugins(MimaPlugin, SitePlugin)
   .aggregate(modules: _*)
   .aggregate(`doc-examples`)
   .settings(
@@ -53,12 +53,11 @@ lazy val alpakka = project
         |
         |Useful sbt tasks:
         |
-        |  docs/Local/paradox - builds documentation with locally
-        |    linked Scala API docs, which can be found at
-        |    docs/target/paradox/site/local
+        |  docs/previewSite - builds Paradox and Scaladoc documentation,
+        |    starts a webserver and opens a new browser window
         |
         |  test - runs all the tests for all of the connectors.
-        |   Make sure to run `docker-compose up` first.
+        |    Make sure to run `docker-compose up` first.
         |
         |  mqtt/testOnly *.MqttSourceSpec - runs a single test
         |
@@ -227,13 +226,33 @@ lazy val unixdomainsocket = alpakkaProject(
 lazy val xml = alpakkaProject("xml", "xml", Dependencies.Xml)
 
 lazy val docs = project
-  .enablePlugins(AkkaParadoxPlugin)
+  .enablePlugins(AkkaParadoxPlugin, ParadoxSitePlugin, PreprocessPlugin, SymlinkPlugin, PublishRsyncPlugin)
   .disablePlugins(BintrayPlugin, MimaPlugin)
   .settings(
     name := "Alpakka",
     publish / skip := true,
     whitesourceIgnore := true,
-    paradoxProperties ++= Map(
+    makeSite := makeSite.dependsOn(LocalRootProject / ScalaUnidoc / doc).value,
+    makeSite := {
+      (Symlink / symlinkCreate).value
+      makeSite.value
+    },
+    Symlink / symlinkPaths ++= Seq(isSnapshot.value).flatMap {
+      case false =>
+        Seq(
+          "api/alpakka/current" -> s"api/alpakka/${version.value}",
+          "docs/alpakka/current" -> s"docs/alpakka/${version.value}",
+        )
+      case true => Seq.empty
+    }.toMap,
+    Preprocess / siteSubdirName := s"api/alpakka/${if (isSnapshot.value) "snapshot" else version.value}",
+    Preprocess / sourceDirectory := (LocalRootProject / ScalaUnidoc / unidoc / target).value,
+    Preprocess / preprocessRules := Seq(
+      ("\\.java\\.scala".r, _ => ".java")
+    ),
+    Paradox / siteSubdirName := s"docs/alpakka/${if (isSnapshot.value) "snapshot" else version.value}",
+    Paradox / sourceDirectory := sourceDirectory.value / "main" / "paradox",
+    Paradox / paradoxProperties ++= Map(
       "project.url" -> "https://developer.lightbend.com/docs/alpakka/current/",
       "akka.version" -> Dependencies.AkkaVersion,
       "akka-http.version" -> Dependencies.AkkaHttpVersion,
@@ -255,17 +274,23 @@ lazy val docs = project
       "scaladoc.scala.base_url" -> s"http://www.scala-lang.org/api/current/",
       "scaladoc.akka.base_url" -> s"http://doc.akka.io/api/akka/${Dependencies.AkkaVersion}",
       "scaladoc.akka.http.base_url" -> s"https://doc.akka.io/api/akka-http/${Dependencies.AkkaHttpVersion}/",
-      "scaladoc.akka.stream.alpakka.base_url" -> s"http://developer.lightbend.com/docs/api/alpakka/${version.value}"
+      "scaladoc.akka.stream.alpakka.base_url" -> {
+        val docsHost = sys.env
+          .get("CI")
+          .map(_ => "https://doc.akka.io")
+          .getOrElse(s"http://localhost:${(previewSite / previewFixedPort).value}")
+        s"$docsHost/api/alpakka/${version.value}/"
+      }
     ),
+    Paradox / paradoxGroups := Map("Language" -> Seq("Java", "Scala")),
     resolvers += Resolver.jcenterRepo,
-    paradoxGroups := Map("Language" -> Seq("Java", "Scala")),
-    paradoxLocalApiKey := "scaladoc.akka.stream.alpakka.base_url",
-    paradoxLocalApiDir := (alpakka / Compile / sbtunidoc.BaseUnidocPlugin.autoImport.unidoc).value.head,
+    publishRsyncArtifact := makeSite.value -> "www/",
+    publishRsyncHost := "akkarepo@gustav.akka.io"
   )
 
 lazy val `doc-examples` = project
   .enablePlugins(AutomateHeaderPlugin)
-  .disablePlugins(BintrayPlugin, MimaPlugin)
+  .disablePlugins(BintrayPlugin, MimaPlugin, SitePlugin)
   .dependsOn(
     modules.map(p => classpathDependency(p)): _*
   )
@@ -279,6 +304,7 @@ lazy val `doc-examples` = project
 def alpakkaProject(projectId: String, moduleName: String, additionalSettings: sbt.Def.SettingsDefinition*): Project =
   Project(id = projectId, base = file(projectId))
     .enablePlugins(AutomateHeaderPlugin)
+    .disablePlugins(SitePlugin)
     .settings(
       name := s"akka-stream-alpakka-$projectId",
       AutomaticModuleName.settings(s"akka.stream.alpakka.$moduleName"),

contributor-advice.md

@@ -180,5 +180,5 @@ unused methods.
 
 Use ScalaDoc if you see the need to describe the API usage better than the naming does.
 
-Run `sbt docs/Local/paradox` to generate reference docs while developing. Generated documentation can be 
-found in the `./docs/target/paradox/site/local` directory.
+Run `sbt docs/makeSite` to generate reference and API docs while developing. Generated documentation can be
+found in the `./docs/target/site` directory.

project/Publish.scala

@@ -13,22 +13,3 @@ object Publish extends AutoPlugin {
     bintrayRepository := (if (isSnapshot.value) "snapshots" else "maven")
   )
 }
-
-object PublishUnidoc extends AutoPlugin {
-  import sbtunidoc.BaseUnidocPlugin.autoImport._
-  import sbtunidoc.ScalaUnidocPlugin.autoImport.ScalaUnidoc
-
-  override def requires = sbtunidoc.ScalaUnidocPlugin
-
-  def publishOnly(artifactType: String)(config: PublishConfiguration) = {
-    val newArts = config.artifacts.filter(_._1.`type` == artifactType)
-    config.withArtifacts(newArts)
-  }
-
-  override def projectSettings = Seq(
-    doc in Compile := (doc in ScalaUnidoc).value,
-    target in unidoc in ScalaUnidoc := crossTarget.value / "api",
-    publishConfiguration ~= publishOnly(Artifact.DocType),
-    publishLocalConfiguration ~= publishOnly(Artifact.DocType)
-  )
-}

project/PublishRsync.scala

@@ -0,0 +1,27 @@
+import com.typesafe.sbt.site.SitePlugin
+import sbt._
+import scala.sys.process._
+
+trait PublishRsyncKeys {
+  val publishRsyncArtifact = taskKey[(File, String)]("File or directory and a path to publish to")
+  val publishRsyncHost = settingKey[String]("hostname to publish to")
+  val publishRsync = taskKey[Int]("Deploy using rsync")
+}
+
+object PublishRsyncPlugin extends AutoPlugin {
+
+  override def requires = SitePlugin
+  override def trigger = noTrigger
+
+  object autoImport extends PublishRsyncKeys
+  import autoImport._
+
+  override def projectSettings = publishRsyncSettings()
+
+  def publishRsyncSettings(): Seq[Setting[_]] = Seq(
+    publishRsync := {
+      val (from, to) = publishRsyncArtifact.value
+      s"rsync -azP $from/ ${publishRsyncHost.value}:$to" !
+    }
+  )
+}

project/SymlinkPlugin.scala

@@ -0,0 +1,48 @@
+import java.nio.file.Files
+
+import com.typesafe.sbt.site.SitePlugin
+import com.typesafe.sbt.site.SitePlugin.autoImport._
+import sbt._
+import sbt.Keys._
+
+trait SymlinkKeys {
+  val symlinkPaths = settingKey[Map[String, String]]("Symbolic links to create: link -> source")
+  val symlinkCreate = taskKey[File]("Creates symlinks according to 'symlinkPaths' setting value")
+}
+
+object SymlinkPlugin extends AutoPlugin {
+
+  override def requires = SitePlugin
+  override def trigger = noTrigger
+
+  object autoImport extends SymlinkKeys {
+    val Symlink = config("symlink")
+  }
+  import autoImport._
+
+  override def projectSettings = symlinkSettings(Symlink)
+
+  def symlinkSettings(config: Configuration): Seq[Setting[_]] =
+    inConfig(config)(
+      Seq(
+        target := (makeSite / target).value,
+        symlinkPaths := Map.empty,
+        symlinkCreate := createSymlinks(symlinkPaths.value, target.value)
+      )
+    )
+
+  private def createSymlinks(definitions: Map[String, String], targetDir: File) = {
+    definitions.map {
+      case (link, source) =>
+        val target = targetDir.toPath
+
+        val linkResolved = target.resolve(link)
+        linkResolved.getParent.toFile.mkdirs()
+
+        linkResolved.toFile.delete()
+        val relative = linkResolved.getParent.relativize(target.resolve(source))
+        Files.createSymbolicLink(linkResolved, relative)
+    }
+    targetDir
+  }
+}

project/plugins.sbt

@@ -10,12 +10,13 @@ addSbtPlugin("com.thoughtworks.sbt-api-mappings" % "sbt-api-mappings" % "2.1.0")
 addSbtPlugin("org.foundweekends" % "sbt-bintray" % "0.5.4")
 addSbtPlugin("com.typesafe" % "sbt-mima-plugin" % "0.3.0")
 addSbtPlugin("com.lightbend" % "sbt-whitesource" % "0.1.13")
-addSbtPlugin("lt.dvim.paradox" % "sbt-paradox-local" % "0.2")
+addSbtPlugin("com.typesafe.sbt" % "sbt-site" % "1.3.3-2m")
+addSbtPlugin("com.eed3si9n" % "sbt-unidoc" % "0.4.2")
 addSbtPlugin("com.lightbend.sbt" % "sbt-java-formatter" % "0.4.1")
 addSbtPlugin("com.lightbend.akka.grpc" % "sbt-akka-grpc" % "0.4")
 addSbtPlugin("com.lightbend.sbt" % "sbt-javaagent" % "0.1.4")
 addSbtPlugin("pl.project13.scala" % "sbt-jmh" % "0.3.4")
-// patched version of sbt-dependency-graph
 // depend directly on the patched version see https://github.com/akka/alpakka/issues/1388
 addSbtPlugin("net.virtual-void" % "sbt-dependency-graph" % "0.9.2+10-148ba0ff")
+// patched version of sbt-dependency-graph and sbt-site
 resolvers += Resolver.bintrayIvyRepo("2m", "sbt-plugins")