From 990ac435a82c1202912772de0e86cd3438f46dca Mon Sep 17 00:00:00 2001 From: Enno <458526+ennru@users.noreply.github.com> Date: Mon, 7 Oct 2019 16:23:22 +0200 Subject: [PATCH] Scaladoc/Javadoc: wrap link text in '' (#378) * Scaladoc/Javadoc: wrap link text in '' * Adapt unit tests --- .../paradox/markdown/Directive.scala | 10 ++++-- .../paradox/parameterized-links/build.sbt | 2 +- .../parameterized-links/expected/javadoc.html | 6 ++-- .../expected/scaladoc.html | 6 ++-- .../scaladoc-2.12/expected/scaladoc-2.12.html | 4 +-- .../markdown/JavadocDirectiveSpec.scala | 20 ++++++------ .../markdown/ScaladocDirectiveSpec.scala | 32 +++++++++---------- 7 files changed, 42 insertions(+), 38 deletions(-) diff --git a/core/src/main/scala/com/lightbend/paradox/markdown/Directive.scala b/core/src/main/scala/com/lightbend/paradox/markdown/Directive.scala index 6daa6b27..32f5c56d 100644 --- a/core/src/main/scala/com/lightbend/paradox/markdown/Directive.scala +++ b/core/src/main/scala/com/lightbend/paradox/markdown/Directive.scala @@ -212,10 +212,12 @@ object LinkDirective { abstract class ExternalLinkDirective(names: String*) extends InlineDirective(names: _*) with SourceDirective { - def resolveLink(node: DirectiveNode, location: String): Url + protected def resolveLink(node: DirectiveNode, location: String): Url def render(node: DirectiveNode, visitor: Visitor, printer: Printer): Unit = - new ExpLinkNode(title(node, page), resolvedSource(node, page), node.contentsNode).accept(visitor) + new ExpLinkNode(title(node, page), resolvedSource(node, page), linkContents(node)).accept(visitor) + + protected def linkContents(node: DirectiveNode): Node = node.contentsNode override protected def resolvedSource(node: DirectiveNode, page: Page): String = { val link = super.resolvedSource(node, page) @@ -279,6 +281,8 @@ abstract class ApiDocDirective(name: String) case (property @ ApiDocProperty(pkg), url) => (pkg, PropertyUrl(property, variables.get)) } + override protected def linkContents(node: DirectiveNode): Node = new CodeNode(node.contents) + override protected def title(node: DirectiveNode, page: Page): String = { val link = extractLink(node, page) try { @@ -296,7 +300,7 @@ abstract class ApiDocDirective(name: String) } } - def resolveLink(node: DirectiveNode, link: String): Url = { + override protected def resolveLink(node: DirectiveNode, link: String): Url = { val levels = link.split("[.]") val packages = (1 to levels.init.size).map(levels.take(_).mkString(".")) val baseUrl = packages.reverse.collectFirst(baseUrls).getOrElse(defaultBaseUrl).resolve() diff --git a/plugin/src/sbt-test/paradox/parameterized-links/build.sbt b/plugin/src/sbt-test/paradox/parameterized-links/build.sbt index 90016151..dba31648 100644 --- a/plugin/src/sbt-test/paradox/parameterized-links/build.sbt +++ b/plugin/src/sbt-test/paradox/parameterized-links/build.sbt @@ -33,5 +33,5 @@ TaskKey[Unit]("checkJavadocJavalibContent") := { assert(file.exists, s"${file.getAbsolutePath} did not exist") val content = IO.readLines(file).mkString assert(content.matches( - raw"""

File\.separator

""")) + raw"""

File\.separator

""")) } diff --git a/plugin/src/sbt-test/paradox/parameterized-links/expected/javadoc.html b/plugin/src/sbt-test/paradox/parameterized-links/expected/javadoc.html index 81a662ea..bf8f1903 100644 --- a/plugin/src/sbt-test/paradox/parameterized-links/expected/javadoc.html +++ b/plugin/src/sbt-test/paradox/parameterized-links/expected/javadoc.html @@ -1,3 +1,3 @@ -

Actor

-

Http

-

Server

+

Actor

+

Http

+

Server

diff --git a/plugin/src/sbt-test/paradox/parameterized-links/expected/scaladoc.html b/plugin/src/sbt-test/paradox/parameterized-links/expected/scaladoc.html index 3929ec62..05641113 100644 --- a/plugin/src/sbt-test/paradox/parameterized-links/expected/scaladoc.html +++ b/plugin/src/sbt-test/paradox/parameterized-links/expected/scaladoc.html @@ -1,3 +1,3 @@ -

Use a Future to avoid that long running operations block the Actor.

-

Http

-

Server#start

+

Use a Future to avoid that long running operations block the Actor.

+

Http

+

Server#start

diff --git a/plugin/src/sbt-test/paradox/scaladoc-2.12/expected/scaladoc-2.12.html b/plugin/src/sbt-test/paradox/scaladoc-2.12/expected/scaladoc-2.12.html index 99f8e2b1..0c5e9d00 100644 --- a/plugin/src/sbt-test/paradox/scaladoc-2.12/expected/scaladoc-2.12.html +++ b/plugin/src/sbt-test/paradox/scaladoc-2.12/expected/scaladoc-2.12.html @@ -1,2 +1,2 @@ -

Use a Future to avoid that long running operations block the Actor.

-

Http

+

Use a Future to avoid that long running operations block the Actor.

+

Http

diff --git a/tests/src/test/scala/com/lightbend/paradox/markdown/JavadocDirectiveSpec.scala b/tests/src/test/scala/com/lightbend/paradox/markdown/JavadocDirectiveSpec.scala index 239527bf..367e211c 100644 --- a/tests/src/test/scala/com/lightbend/paradox/markdown/JavadocDirectiveSpec.scala +++ b/tests/src/test/scala/com/lightbend/paradox/markdown/JavadocDirectiveSpec.scala @@ -32,39 +32,39 @@ class JavadocDirectiveSpec extends MarkdownBaseSpec { "javadoc directive" should "create links using configured URL templates" in { markdown("@javadoc[Publisher](org.reactivestreams.Publisher)") shouldEqual - html("""

Publisher

""") + html("""

Publisher

""") } it should "support 'javadoc:' as an alternative name" in { markdown("@javadoc:[Publisher](org.reactivestreams.Publisher)") shouldEqual - html("""

Publisher

""") + html("""

Publisher

""") } it should "support root relative '...' base urls" in { markdown("@javadoc[Url](root.relative.Url)") shouldEqual - html("""

Url

""") + html("""

Url

""") } it should "handle method links correctly" in { markdown("@javadoc[File.pathSeparator](java.io.File#pathSeparator)") shouldEqual - html("""

File.pathSeparator

""") + html("""

File.pathSeparator

""") } it should "handle class links correctly" in { markdown("@javadoc[Http](akka.http.javadsl.Http)") shouldEqual - html("""

Http

""") + html("""

Http

""") markdown("@javadoc[Actor](akka.actor.Actor)") shouldEqual - html("""

Actor

""") + html("""

Actor

""") } it should "retain whitespace before or after" in { markdown("The @javadoc:[Actor](akka.actor.Actor) class") shouldEqual - html("""

The Actor class

""") + html("""

The Actor class

""") } it should "parse but ignore directive attributes" in { markdown("The @javadoc:[Publisher](org.reactivestreams.Publisher) { .javadoc a=1 } spec") shouldEqual - html("""

The Publisher spec

""") + html("""

The Publisher spec

""") } it should "throw exceptions for unconfigured default base URL" in { @@ -91,13 +91,13 @@ class JavadocDirectiveSpec extends MarkdownBaseSpec { | | [Publisher]: org.reactivestreams.Publisher """.stripMargin) shouldEqual - html("""

The Publisher spec

""") + html("""

The Publisher spec

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

Publisher

""") + html("""

Publisher

""") } } diff --git a/tests/src/test/scala/com/lightbend/paradox/markdown/ScaladocDirectiveSpec.scala b/tests/src/test/scala/com/lightbend/paradox/markdown/ScaladocDirectiveSpec.scala index 6c6c0786..cc9d0542 100644 --- a/tests/src/test/scala/com/lightbend/paradox/markdown/ScaladocDirectiveSpec.scala +++ b/tests/src/test/scala/com/lightbend/paradox/markdown/ScaladocDirectiveSpec.scala @@ -31,45 +31,45 @@ class ScaladocDirectiveSpec extends MarkdownBaseSpec { "Scaladoc directive" should "create links using configured URL templates" in { markdown("@scaladoc[Model](org.example.Model)") shouldEqual - html("""

Model

""") + html("""

Model

""") } it should "support 'scaladoc:' as an alternative name" in { markdown("@scaladoc:[Model](org.example.Model)") shouldEqual - html("""

Model

""") + html("""

Model

""") } it should "support root relative '...' base urls" in { markdown("@scaladoc:[Url](root.relative.Url)") shouldEqual - html("""

Url

""") + html("""

Url

""") } it should "handle method links correctly" in { markdown("@scaladoc[???](scala.Predef$#???:Nothing)") shouldEqual - html("""

???

""") + html("""

???

""") markdown( """@scaladoc:[Actor#preStart] | | [Actor#preStart]: akka.actor.Actor#preStart():Unit""") shouldEqual - html("""

Actor#preStart

""") + html("""

Actor#preStart

""") } it should "handle object links correctly" in { markdown("@scaladoc[Http](akka.http.scaladsl.Http$)") shouldEqual - html("""

Http

""") + html("""

Http

""") markdown("@scaladoc[Actor](akka.actor.Actor)") shouldEqual - html("""

Actor

""") + html("""

Actor

""") } it should "retain whitespace before or after" in { markdown("The @scaladoc:[Model](org.example.Model) class") shouldEqual - html("""

The Model class

""") + html("""

The Model class

""") } it should "parse but ignore directive attributes" in { markdown("The @scaladoc:[Model](org.example.Model) { .scaladoc a=1 } spec") shouldEqual - html("""

The Model spec

""") + html("""

The Model spec

""") } it should "throw exceptions for unconfigured default base URL" in { @@ -90,11 +90,11 @@ class ScaladocDirectiveSpec extends MarkdownBaseSpec { "scaladoc.version" -> "2.12.0") markdown("@scaladoc[Int](scala.Int)") shouldEqual - html("""

Int

""") + html("""

Int

""") markdown("@scaladoc[Codec$](scala.io.Codec$)") shouldEqual - html("""

Codec$

""") + html("""

Codec$

""") markdown("@scaladoc[scala.io package](scala.io.index)") shouldEqual - html("""

scala.io package

""") + html("""

scala.io package

""") } it should "support Scala 2.11 links" in { @@ -103,11 +103,11 @@ class ScaladocDirectiveSpec extends MarkdownBaseSpec { "scaladoc.version" -> "2.11.12") markdown("@scaladoc[Int](scala.Int)") shouldEqual - html("""

Int

""") + html("""

Int

""") markdown("@scaladoc[Codec$](scala.io.Codec$)") shouldEqual - html("""

Codec$

""") + html("""

Codec$

""") markdown("@scaladoc[scala.io package](scala.io.package)") shouldEqual - html("""

scala.io package

""") + html("""

scala.io package

""") } it should "support referenced links" in { @@ -116,6 +116,6 @@ class ScaladocDirectiveSpec extends MarkdownBaseSpec { | | [1]: org.example.Model """) shouldEqual - html("""

The Model spec

""") + html("""

The Model spec

""") } }