Merge pull request #355 from jroper/javadoc-link-style

Made javadoc link style configurable

core/src/main/scala/com/lightbend/paradox/markdown/Directive.scala

@@ -294,13 +294,26 @@ case class ScaladocDirective(page: Page, variables: Map[String, String])
 
 }
 
+object JavadocDirective {
+  // If Java 9+ we default to linking directly to the file, since it doesn't support frames, otherwise we default
+  // to linking to the frames version with the class in the query parameter. Also, the version of everything up to
+  // and including 8 starts with 1., so that's an easy way to tell if it's 9+ or not.
+  val framesLinkStyle = sys.props.get("java.specification.version").exists(_.startsWith("1."))
+}
+
 case class JavadocDirective(page: Page, variables: Map[String, String])
   extends ApiDocDirective("javadoc", page, variables) {
 
+  val framesLinkStyle = variables.get("javadoc.link_style").fold(JavadocDirective.framesLinkStyle)(_ == "frames")
+
   def resolveApiLink(baseUrl: Url, link: String): Url = {
     val url = Url(link).base
     val path = url.getPath.replace('.', '/') + ".html"
-    baseUrl.withEndingSlash.withQuery(path).withFragment(url.getFragment)
+    if (framesLinkStyle) {
+      baseUrl.withEndingSlash.withQuery(path).withFragment(url.getFragment)
+    } else {
+      (baseUrl / path) withFragment url.getFragment
+    }
   }
 
 }

docs/src/main/paradox/directives/linking.md

@@ -97,7 +97,15 @@ For example, given:
  - `javadoc.akka.http.base_url=http://doc.akka.io/japi/akka-http/10.0.0`
 
 Then `@javadoc[Http](akka.http.javadsl.Http#shutdownAllConnectionPools--)` will resolve to
-<http://doc.akka.io/japi/akka-http/10.0.0/akka/http/javadsl/Http.html#shutdownAllConnectionPools-->.
+<http://doc.akka.io/japi/akka-http/10.0.0/?akka/http/javadsl/Http.html#shutdownAllConnectionPools-->.
+
+The `@javadoc` directive offers two styles of linking, linking to the frames version of
+the apidocs, and linking to the non frames version. This can be controlled using the `javadoc.link_style`
+property, setting it to `frames` for frames style linking, where rendered links link to the frames
+version of the javadocs, passing the class in the query parameter, and `direct` for linking direct
+to the classes page. The link style defaults to `direct` if the `java.specification.version` system
+property indicates Java 9+, since the JDK 9 Javadoc tool does not generate framed api docs. Otherwise,
+for Java 1.8 and earlier, it defaults to `frames`.
 
 By default, `javadoc.java.base_url` is configured to the Javadoc
 associated with the `java.specification.version` system property.

plugin/src/sbt-test/paradox/parameterized-links/build.sbt

@@ -11,6 +11,7 @@ paradoxProperties in Compile ++= Map(
   "extref.akka-docs.base_url" -> s"http://doc.akka.io/docs/akka/$akkaVersion/%s.html",
   "scaladoc.akka.base_url" -> s"http://doc.akka.io/api/akka/$akkaVersion",
   "scaladoc.akka.http.base_url" -> s"http://doc.akka.io/api/akka-http/$akkaHttpVersion",
+  "javadoc.link_style" -> "frames",
   "javadoc.base_url" -> s"https://api.example.com/java",
   "javadoc.akka.base_url" -> s"http://doc.akka.io/japi/akka/$akkaVersion",
   "javadoc.akka.http.base_url" -> s"http://doc.akka.io/japi/akka-http/$akkaHttpVersion"

tests/src/test/scala/com/lightbend/paradox/markdown/JavadocDirectiveSpec.scala

@@ -16,12 +16,11 @@
 
 package com.lightbend.paradox.markdown
 
-import com.lightbend.paradox.tree.Tree.Location
-
 class JavadocDirectiveSpec extends MarkdownBaseSpec {
 
   implicit val context = writerContextWithProperties(
     "javadoc.base_url" -> "http://www.reactive-streams.org/reactive-streams-1.0.0-javadoc/",
+    "javadoc.link_style" -> "frames",
     "javadoc.java.base_url" -> "https://docs.oracle.com/javase/8/docs/api/",
     "javadoc.akka.base_url" -> "http://doc.akka.io/japi/akka/2.4.10",
     "javadoc.akka.http.base_url" -> "http://doc.akka.io/japi/akka-http/10.0.0/index.html",
@@ -93,4 +92,10 @@ class JavadocDirectiveSpec extends MarkdownBaseSpec {
       html("""<p>The <a href="http://www.reactive-streams.org/reactive-streams-1.0.0-javadoc/?org/reactivestreams/Publisher.html">Publisher</a> spec</p>""")
   }
 
+  it should "support creating non frame style links" in {
+    val ctx = context.andThen(c => c.copy(properties = c.properties.updated("javadoc.link_style", "direct")))
+    markdown("@javadoc[Publisher](org.reactivestreams.Publisher)")(ctx) shouldEqual
+      html("""<p><a href="http://www.reactive-streams.org/reactive-streams-1.0.0-javadoc/org/reactivestreams/Publisher.html">Publisher</a></p>""")
+  }
+
 }