From 4d04bb968bc2266e5a2d35f15ff45e645f6b17c6 Mon Sep 17 00:00:00 2001 From: Enno <458526+ennru@users.noreply.github.com> Date: Tue, 3 Dec 2019 09:16:05 +0100 Subject: [PATCH] Docs: add some API links to stream operator docs (#28180) * Docs: add some API links to stream operator docs * Complement CONTRIBUTION.md * Switch to frameless Javadoc --- CONTRIBUTING.md | 10 ++++++++++ .../paradox/stream/operators/Source-or-Flow/filter.md | 3 +++ .../stream/operators/Source-or-Flow/filterNot.md | 3 +++ project/Doc.scala | 5 ++--- project/Paradox.scala | 2 ++ project/plugins.sbt | 2 +- 6 files changed, 21 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ef0ba654f6..65ef5bd2ae 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -312,6 +312,16 @@ akka-docs/paradox The generated html documentation is in `akka-docs/target/paradox/site/main/index.html`. +Alternatively, use `akka-docs/paradoxBrowse` to open the generated docs in your default web browser. + +### Links to API documentation + +Akka Paradox supports directives to link to the Scaladoc- and Javadoc-generated API documentation: + +* `@apidoc[Flow]` searches for the class name and creates links to Scaladoc and Javadoc (see variants in [sbt-paradox-apidoc](https://github.com/lightbend/sbt-paradox-apidoc#examples)) +* `@scaladoc[Flow](akka.stream.scaladsl.Flow)` (see [Paradox docs](https://developer.lightbend.com/docs/paradox/current/directives/linking.html#scaladoc-directive)) +* `@javadoc[Flow](akka.stream.javadsl.Flow)` (see [Paradox docs](https://developer.lightbend.com/docs/paradox/current/directives/linking.html#javadoc-directive)) + ### Scaladoc Akka generates class diagrams for the API documentation using ScalaDoc. diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/filter.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/filter.md index d335ce82f2..2598a7325d 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/filter.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/filter.md @@ -41,3 +41,6 @@ Java @@@ +## API docs + +@apidoc[Flow.filter](Flow) { scala="#filter(p:Out=%3EBoolean):FlowOps.this.Repr[Out]" java="#filter(akka.japi.function.Predicate)" } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/filterNot.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/filterNot.md index 3b827de0a5..8ea399269e 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/filterNot.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/filterNot.md @@ -41,3 +41,6 @@ Java @@@ +## API docs + +@apidoc[Flow.filterNot](Flow) { scala="#filterNot(p:Out=%3EBoolean):FlowOps.this.Repr[Out]" java="#filterNot(akka.japi.function.Predicate)" } diff --git a/project/Doc.scala b/project/Doc.scala index f9c2606b5f..a9f0572744 100644 --- a/project/Doc.scala +++ b/project/Doc.scala @@ -57,8 +57,7 @@ object Scaladoc extends AutoPlugin { "-doc-version", ver, "-doc-canonical-base-url", - "https://doc.akka.io/api/akka/current/" - ) + "https://doc.akka.io/api/akka/current/") CliOptions.scaladocDiagramsEnabled.ifTrue("-diagrams").toList ::: opts } @@ -135,7 +134,7 @@ object UnidocRoot extends AutoPlugin { val akkaSettings = UnidocRoot.CliOptions.genjavadocEnabled .ifTrue(Seq(javacOptions in (JavaUnidoc, unidoc) := { if (JdkOptions.isJdk8) Seq("-Xdoclint:none") - else Seq("-Xdoclint:none", "--frames", "--ignore-source-errors", "--no-module-directories") + else Seq("-Xdoclint:none", "--ignore-source-errors", "--no-module-directories") })) .getOrElse(Nil) diff --git a/project/Paradox.scala b/project/Paradox.scala index 8c39e4ab4f..6e76d5a79f 100644 --- a/project/Paradox.scala +++ b/project/Paradox.scala @@ -26,7 +26,9 @@ object Paradox { "scaladoc.akka.base_url" -> "https://doc.akka.io/api/akka/2.6", "scaladoc.akka.http.base_url" -> "https://doc.akka.io/api/akka-http/current", "javadoc.akka.base_url" -> "https://doc.akka.io/japi/akka/2.6", + "javadoc.akka.link_style" -> "direct", "javadoc.akka.http.base_url" -> "https://doc.akka.io/japi/akka-http/current", + "javadoc.akka.http.link_style" -> "frames", "scala.version" -> scalaVersion.value, "scala.binary_version" -> scalaBinaryVersion.value, "akka.version" -> version.value, diff --git a/project/plugins.sbt b/project/plugins.sbt index 3cb4611736..f0245cf8c7 100644 --- a/project/plugins.sbt +++ b/project/plugins.sbt @@ -18,7 +18,7 @@ addSbtPlugin("com.eed3si9n" % "sbt-unidoc" % "0.4.2") addSbtPlugin("com.thoughtworks.sbt-api-mappings" % "sbt-api-mappings" % "3.0.0") addSbtPlugin("pl.project13.scala" % "sbt-jmh" % "0.3.7") addSbtPlugin("io.spray" % "sbt-boilerplate" % "0.6.1") -addSbtPlugin("com.lightbend.akka" % "sbt-paradox-akka" % "0.26") +addSbtPlugin("com.lightbend.akka" % "sbt-paradox-akka" % "0.27") addSbtPlugin("com.lightbend" % "sbt-whitesource" % "0.1.18") addSbtPlugin("de.heikoseeberger" % "sbt-header" % "5.3.1") // for maintenance of copyright file header addSbtPlugin("com.hpe.sbt" % "sbt-pull-request-validator" % "1.0.0")