Add @extref, @scaladoc and @github directives for parameterized linking to external pages

[jonas]

As suggested by @pvlugter it allows to configure simple URI templates similar to Slick's apilink extension. The templates can be configured via Paradox properties prefixed with links.ext and the lookup uses uses the URI scheme, examples:

• @ext[Actor](scaladoc:akka.actor.Actor)
• @ext[#1](issue:1)

I considered naming it @link as that might be more telling when viewing in GitHub. Let me know if you have better suggestions.

Possible extensions and improvements:

• "built-in templates"
  • scala which links to Scala's scaladoc using scalaVersion setting
  • java which links to Java lang javadocs
  • api which links to the current project's scaladoc using apiURL from the Ivy XML/model (if defined)
  • issue which link to tickets using project's scmInfo (i.e. ScmInfo.browseUrl) (if defined)
  • github which would support GitHub specific links: akka/akka#1234, akka/akka@0f2da7b26b5c and optionally use project defined in SBT's scmInfo setting to support more relative project links
• "link types", such as

  • 'scaladoc' to better support links to methods etc. e.g.

      @ext[ask pattern](akka-scaladoc:akka.pattern.package#ask(actorSelection:akka.actor.ActorSelection):akka.pattern.AskableActorSelection)
    

[eed3si9n]

I would request a feature to override the base URL for the scaladocs/javadocs so in the future we could host Lightbend-related API docs on Tech Hub.

[jonas]

@eed3si9n I can add a scripted test to validate, but since the URL templates are configurable via the paradoxProperties settings this should already be the case.

sbt 'project docs' \
  'set paradoxProperties ++= Map("scaladoc" -> "http://developer.lightbend.com/akka-http/scaladoc/10.0.0/#%s")' \
  paradox

[eed3si9n]

In terms of names, I'm not sure about @ext. It kind of reminds me of "extension", and I'm not sure if the term "external" makes sense if the link is towards your own domain.
If we know exactly what these could be used for why not name them @scaladoc[Actor](akka.actor.Actor), @github[#1](akka/akka#1). It's less extensible, but might be more clearer in text.

[jonas]

For Akka HTTP my understanding is that it needs to have "parametrized" links for:

• doc.akka.io using Dependencies.akkaVersion
• scaladoc/javadoc for using version (as mentioned in Provide in-line directive for linking to ScalaDoc #2)
• GitHub blobs using version

For concepts related to streaming and Akka core usage I'd also imagine having links to Akka scaladoc/javadoc would be useful, not to mention links to Scala language scaladoc and Java language javadoc.

Slick has 9 URL templates, 2 of which are parameterized:

• https://github.com/slick/slick/blob/master/slick/src/sphinx/conf.py#L251-L264

[eed3si9n]

For the apilinks, we can semi-automate it so the package starting with scala goes to http://www.scala-lang.org/api/ with some Scala version so on the text source it should show up as:

@scaladoc[Actor](akka.actor.Actor) and @scaladoc[Future](scala.concurrent.Future).

Similarly Github can support both my project and others:

@github[#1](#1) and @github[#1](some/others#1)

I'm ok with keeping ext for all other things specific to a particular document. How about extref as a name?

[jonas]

Great idea. Should we keep configuration under a common prefix?

# Automatically set looking at SBT `scmInfo` setting
links.github=https://github.com/akka/akka-http

# links.scaladoc.<package-prefix>: uses the package prefix to route to the right scaladoc site
links.scaladoc.scala=http://scala-lang.org/api/${scalaVersion.value}/#%s
links.scaladoc.akka=http://doc.akka.io/api/akka/${Dependencies.akkaVersion}#%s
# "catch all" without prefix
links.scaladoc=http://doc.akka.io/api/akka-http/${version.value.replaceAll(".*-SNAPSHOT", "latest")}#%s

# An escape hatch for custom links
# @extref[RFC 7230](rfc:7230#section-3.3.3) -> http://tools.ietf.org/html/rfc7230#section-3.3.3
links.extref.rfc=http://tools.ietf.org/html/rfc%s

[eed3si9n]

How about we come call these properties "base_url" or something?

# Automatically set looking at SBT `scmInfo` setting
github.base_url=https://github.com/akka/akka-http

# scaladoc.<package-prefix>.base_url: uses the package prefix to route to the right scaladoc site
scaladoc.scala.base_url=http://scala-lang.org/api/${scalaVersion.value}/#%s
scaladoc.akka.base_url=http://doc.akka.io/api/akka/${Dependencies.akkaVersion}#%s
# "catch all" without prefix
scaladoc.base_url=http://doc.akka.io/api/akka-http/${version.value.replaceAll(".*-SNAPSHOT", "latest")}#%s

# An escape hatch for custom links
# @extref[RFC 7230](rfc:7230#section-3.3.3) -> http://tools.ietf.org/html/rfc7230#section-3.3.3
extref.rfc.base_url=http://tools.ietf.org/html/rfc%s

[jonas]

👍 I will update the PR.

[jonas]

@eed3si9n I've updated the PR with the new functionality. I hope this gets it close to something mergeable.

WIP branch that I'd like to land in Akka HTTP once this PR gets merged and a new version has been released: https://github.com/jonas/akka-http/tree/external-links

[eed3si9n]

LGTM

[ktoso]

great! :-)

[ktoso]

👍

[pvlugter]

👍 Nice work! Great additions.