raboof/pekko
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions 10

Docs: add some API links to stream operator docs (#28180)

Browse source 
* Docs: add some API links to stream operator docs

* Complement CONTRIBUTION.md

* Switch to frameless Javadoc
This commit is contained in:
Enno 2019-12-03 09:16:05 +01:00 • committed by Arnout Engelen
parent d53d3701fa
commit 4d04bb968b
6 changed files with 21 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

10
CONTRIBUTING.md
View file

@ -312,6 +312,16 @@ akka-docs/paradox
The generated html documentation is in `akka-docs/target/paradox/site/main/index.html`. 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 ### Scaladoc
Akka generates class diagrams for the API documentation using ScalaDoc. Akka generates class diagrams for the API documentation using ScalaDoc.

3
akka-docs/src/main/paradox/stream/operators/Source-or-Flow/filter.md
View file

@ -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)" }

3
akka-docs/src/main/paradox/stream/operators/Source-or-Flow/filterNot.md
View file

@ -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)" }

5
project/Doc.scala
View file

@ -57,8 +57,7 @@ object Scaladoc extends AutoPlugin {
"-doc-version", "-doc-version",
ver, ver,
"-doc-canonical-base-url", "-doc-canonical-base-url",
"https://doc.akka.io/api/akka/current/" "https://doc.akka.io/api/akka/current/")
)
CliOptions.scaladocDiagramsEnabled.ifTrue("-diagrams").toList ::: opts CliOptions.scaladocDiagramsEnabled.ifTrue("-diagrams").toList ::: opts
} }
@ -135,7 +134,7 @@ object UnidocRoot extends AutoPlugin {
val akkaSettings = UnidocRoot.CliOptions.genjavadocEnabled val akkaSettings = UnidocRoot.CliOptions.genjavadocEnabled
.ifTrue(Seq(javacOptions in (JavaUnidoc, unidoc) := { .ifTrue(Seq(javacOptions in (JavaUnidoc, unidoc) := {
if (JdkOptions.isJdk8) Seq("-Xdoclint:none") 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) .getOrElse(Nil)

2
project/Paradox.scala
View file

@ -26,7 +26,9 @@ object Paradox {
"scaladoc.akka.base_url" -> "https://doc.akka.io/api/akka/2.6", "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", "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.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.base_url" -> "https://doc.akka.io/japi/akka-http/current",
"javadoc.akka.http.link_style" -> "frames",
"scala.version" -> scalaVersion.value, "scala.version" -> scalaVersion.value,
"scala.binary_version" -> scalaBinaryVersion.value, "scala.binary_version" -> scalaBinaryVersion.value,
"akka.version" -> version.value, "akka.version" -> version.value,

2
project/plugins.sbt
View file

@ -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("com.thoughtworks.sbt-api-mappings" % "sbt-api-mappings" % "3.0.0")
addSbtPlugin("pl.project13.scala" % "sbt-jmh" % "0.3.7") addSbtPlugin("pl.project13.scala" % "sbt-jmh" % "0.3.7")
addSbtPlugin("io.spray" % "sbt-boilerplate" % "0.6.1") 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("com.lightbend" % "sbt-whitesource" % "0.1.18")
addSbtPlugin("de.heikoseeberger" % "sbt-header" % "5.3.1") // for maintenance of copyright file header 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") addSbtPlugin("com.hpe.sbt" % "sbt-pull-request-validator" % "1.0.0")