Merge pull request #119 from jonas/direct-scaladoc-links

Direct scaladoc links

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

@@ -140,7 +140,8 @@ object RefDirective {
 /**
  * Link to external sites using URI templates.
  */
-abstract class ExternalLinkDirective(names: String*) extends InlineDirective(names: _*) with SourceDirective {
+abstract class ExternalLinkDirective(names: String*)
+    extends InlineDirective(names: _*) with SourceDirective {
 
   import ExternalLinkDirective._
 
@@ -175,7 +176,7 @@ object ExternalLinkDirective {
  * Link to external pages using URL templates.
  */
 case class ExtRefDirective(page: Page, variables: Map[String, String])
-    extends ExternalLinkDirective("extref", "extref:") with SourceDirective {
+    extends ExternalLinkDirective("extref", "extref:") {
 
   def resolveLink(link: String): Url = {
     link.split(":", 2) match {
@@ -222,14 +223,9 @@ case class ScaladocDirective(page: Page, variables: Map[String, String])
     extends ApiDocDirective("scaladoc", page, variables) {
 
   def resolveApiLink(baseUrl: Url, link: String): Url = {
-    variables.getOrElse("scaladoc.version", "???").split('.').take(2) match {
-      case Array("2", "12") =>
-        val url = Url(link).base
-        val path = url.getPath.replace('.', '/') + ".html"
-        baseUrl / path
-      case _ =>
-        baseUrl.withEndingSlash.withFragment(link)
-    }
+    val url = Url(link).base
+    val path = url.getPath.replace('.', '/') + ".html"
+    (baseUrl / path) withFragment (url.getFragment)
   }
 
 }
@@ -253,7 +249,7 @@ case class JavadocDirective(page: Page, variables: Map[String, String])
  * https://help.github.com/articles/autolinked-references-and-urls/
  */
 case class GitHubDirective(page: Page, variables: Map[String, String])
-    extends ExternalLinkDirective("github", "github:") with SourceDirective {
+    extends ExternalLinkDirective("github", "github:") {
 
   val IssuesLink = """([^/]+/[^/]+)?#([0-9]+)""".r
   val CommitLink = """(([^/]+/[^/]+)?@)?(\p{XDigit}{5,40})""".r

core/src/test/scala/com/lightbend/paradox/markdown/ScaladocDirectiveSpec.scala

@@ -21,41 +21,47 @@ class ScaladocDirectiveSpec extends MarkdownBaseSpec {
   implicit val context = writerContextWithProperties(
     "scaladoc.base_url" -> "http://example.org/api/0.1.2/",
     "scaladoc.scala.base_url" -> "http://www.scala-lang.org/api/2.11.8/",
-    "scaladoc.akka.base_url" -> "http://doc.akka.io/api/akka/2.4.10/index.html",
+    "scaladoc.akka.base_url" -> "http://doc.akka.io/api/akka/2.4.10",
     "scaladoc.akka.http.base_url" -> "http://doc.akka.io/api/akka-http/10.0.0",
     "scaladoc.broken.base_url" -> "https://c|"
   )
 
   "Scaladoc directive" should "create links using configured URL templates" in {
     markdown("@scaladoc[Model](org.example.Model)") shouldEqual
-      html("""<p><a href="http://example.org/api/0.1.2/#org.example.Model">Model</a></p>""")
+      html("""<p><a href="http://example.org/api/0.1.2/org/example/Model.html">Model</a></p>""")
   }
 
   it should "support 'scaladoc:' as an alternative name" in {
     markdown("@scaladoc:[Model](org.example.Model)") shouldEqual
-      html("""<p><a href="http://example.org/api/0.1.2/#org.example.Model">Model</a></p>""")
+      html("""<p><a href="http://example.org/api/0.1.2/org/example/Model.html">Model</a></p>""")
   }
 
   it should "handle method links correctly" in {
-    markdown("@scaladoc[???](scala.Predef$@???:Nothing)") shouldEqual
-      html("""<p><a href="http://www.scala-lang.org/api/2.11.8/#scala.Predef$@???:Nothing">???</a></p>""")
+    markdown("@scaladoc[???](scala.Predef$#???:Nothing)") shouldEqual
+      html("""<p><a href="http://www.scala-lang.org/api/2.11.8/scala/Predef$.html#???:Nothing">???</a></p>""")
+
+    markdown(
+      """@scaladoc:[Actor#preStart]
+        |
+        |  [Actor#preStart]: akka.actor.Actor#preStart():Unit""") shouldEqual
+      html("""<p><a href="http://doc.akka.io/api/akka/2.4.10/akka/actor/Actor.html#preStart():Unit">Actor#preStart</a></p>""")
   }
 
   it should "handle object links correctly" in {
     markdown("@scaladoc[Http](akka.http.scaladsl.Http$)") shouldEqual
-      html("""<p><a href="http://doc.akka.io/api/akka-http/10.0.0/#akka.http.scaladsl.Http$">Http</a></p>""")
+      html("""<p><a href="http://doc.akka.io/api/akka-http/10.0.0/akka/http/scaladsl/Http$.html">Http</a></p>""")
     markdown("@scaladoc[Actor](akka.actor.Actor)") shouldEqual
-      html("""<p><a href="http://doc.akka.io/api/akka/2.4.10/index.html#akka.actor.Actor">Actor</a></p>""")
+      html("""<p><a href="http://doc.akka.io/api/akka/2.4.10/akka/actor/Actor.html">Actor</a></p>""")
   }
 
   it should "retain whitespace before or after" in {
     markdown("The @scaladoc:[Model](org.example.Model) class") shouldEqual
-      html("""<p>The <a href="http://example.org/api/0.1.2/#org.example.Model">Model</a> class</p>""")
+      html("""<p>The <a href="http://example.org/api/0.1.2/org/example/Model.html">Model</a> class</p>""")
   }
 
   it should "parse but ignore directive attributes" in {
     markdown("The @scaladoc:[Model](org.example.Model) { .scaladoc a=1 } spec") shouldEqual
-      html("""<p>The <a href="http://example.org/api/0.1.2/#org.example.Model">Model</a> spec</p>""")
+      html("""<p>The <a href="http://example.org/api/0.1.2/org/example/Model.html">Model</a> spec</p>""")
   }
 
   it should "throw exceptions for unconfigured default base URL" in {
@@ -79,13 +85,29 @@ class ScaladocDirectiveSpec extends MarkdownBaseSpec {
       html("""<p><a href="http://www.scala-lang.org/api/2.12.0/scala/Int.html">Int</a></p>""")
     markdown("@scaladoc[Codec$](scala.io.Codec$)") shouldEqual
       html("""<p><a href="http://www.scala-lang.org/api/2.12.0/scala/io/Codec$.html">Codec$</a></p>""")
+    markdown("@scaladoc[scala.io package](scala.io.index)") shouldEqual
+      html("""<p><a href="http://www.scala-lang.org/api/2.12.0/scala/io/index.html">scala.io package</a></p>""")
+  }
+
+  it should "support Scala 2.11 links" in {
+    implicit val context = writerContextWithProperties(
+      "scaladoc.scala.base_url" -> "http://www.scala-lang.org/api/2.11.11/",
+      "scaladoc.version" -> "2.11.11")
+
+    markdown("@scaladoc[Int](scala.Int)") shouldEqual
+      html("""<p><a href="http://www.scala-lang.org/api/2.11.11/scala/Int.html">Int</a></p>""")
+    markdown("@scaladoc[Codec$](scala.io.Codec$)") shouldEqual
+      html("""<p><a href="http://www.scala-lang.org/api/2.11.11/scala/io/Codec$.html">Codec$</a></p>""")
+    markdown("@scaladoc[scala.io package](scala.io.package)") shouldEqual
+      html("""<p><a href="http://www.scala-lang.org/api/2.11.11/scala/io/package.html">scala.io package</a></p>""")
   }
 
   it should "support referenced links" in {
     markdown(
       """The @scaladoc:[Model][1] spec
         |
         |  [1]: org.example.Model
-      """.stripMargin) shouldEqual html("""<p>The <a href="http://example.org/api/0.1.2/#org.example.Model">Model</a> spec</p>""")
+      """) shouldEqual
+      html("""<p>The <a href="http://example.org/api/0.1.2/org/example/Model.html">Model</a> spec</p>""")
   }
 }

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

@@ -61,7 +61,11 @@ For example, given:
  - `scaladoc.akka.http.base_url=http://doc.akka.io/api/akka-http/10.0.0`
 
 Then `@scaladoc[Http](akka.http.scaladsl.Http$)` will resolve to
-<http://doc.akka.io/api/akka-http/10.0.0/#akka.http.scaladsl.Http$>.
+<http://doc.akka.io/api/akka-http/10.0.0/akka/http/scaladsl/Http$.html>. To link
+to a package page append `.index` for Scala 2.12 and `.package` for Scaladoc
+generated with versions earlier than 2.12, for example `@scaladoc[scaladsl
+package](akka.http.scaladsl.index)` will resolve to
+<http://doc.akka.io/api/akka-http/10.0.0/akka/http/scaladsl/index.html>.
 
 By default, `scaladoc.scala.base_url` is configured to the Scaladoc
 associated with the configured `scalaVersion`. If the sbt project's

plugin/src/sbt-test/paradox/parameterized-links/expected/scaladoc.html

@@ -1,3 +1,3 @@
-<p>Use a <a href="http://www.scala-lang.org/api/2.11.8/#scala.concurrent.Future">Future</a> to avoid that long running operations block the <a href="http://doc.akka.io/api/akka/2.4.10/#akka.actor.Actor">Actor</a>.</p>
-<p><a href="http://doc.akka.io/api/akka-http/10.0.0/#akka.http.scaladsl.Http$">Http</a></p>
-<p><a href="https://example.org/api/0.1.0/#org.example.Server">Server</a></p>
+<p>Use a <a href="http://www.scala-lang.org/api/2.11.8/scala/concurrent/Future.html">Future</a> to avoid that long running operations block the <a href="http://doc.akka.io/api/akka/2.4.10/akka/actor/Actor.html">Actor</a>.</p>
+<p><a href="http://doc.akka.io/api/akka-http/10.0.0/akka/http/scaladsl/Http$.html">Http</a></p>
+<p><a href="https://example.org/api/0.1.0/org/example/Server.html#start():Unit">Server#start</a></p>

plugin/src/sbt-test/paradox/parameterized-links/src/main/paradox/scaladoc.md

@@ -2,4 +2,6 @@ Use a @scaladoc[Future](scala.concurrent.Future) to avoid that long running oper
 
 @scaladoc[Http](akka.http.scaladsl.Http$)
 
-@scaladoc[Server](org.example.Server)
+@scaladoc[Server#start]
+
+   [Server#start]: org.example.Server#start():Unit