5

I'd like to setup ScalaDoc to link to the standard library, from SBT. I'm using 0.12.4 but I'm going to switch to 0.13 soon. Moreover, I'd like to make the setup simple by using 0.13's support.

The best option would be automatic mapping with 0.13's autoAPIMappings:

//Requires SBT 0.13. However, automatic mapping does not work for the standard library.
autoAPIMappings := true

The scala-library should support it because its pom sets info.apiURL, and that's what SBT reads.

However, this does not work. Neither String nor GenTraversable are hyperlinked. last shows that no option is added to scaladoc arguments.

So:

  1. how can I fix autoAPIMappings?
  2. are there alternatives?
  3. I've not observed this feature working, but maybe I just need another package which sets info.apiUrl. Any packages come to mind? Google seems unhelpful, and it's unobvious how to query for maven packages with some properties, or even how to do full-text search on poms. find ~/.m2 ~/.ivy2 -name '*.pom' -type f|xargs grep info.apiUrl found no results among my 2G of local caches.

(This question might seem a dup of SBT Scaladoc Configuration, but it's for updated configuration and with a different SBT version, so the question is different; moreover, the existing answer shows a deprecated solution).

Community
  • 1
  • 1
Blaisorblade
  • 6,438
  • 1
  • 43
  • 76
  • 1
    `autoAPIMappings := true` works on a minimal test case for me, using Scala 2.10.2 and sbt 0.13.0. `Option`, `Int`, and `GenTraversable` link ok and `last` shows the proper option. `String` does not, because it goes to java.lang.String, which is javadoc and not supported by scaladoc. – Mark Harrah Sep 11 '13 at 19:47
  • @MarkHarrah: Thanks for the answer! But it doesn't work for me on this minimal testcase (both Int and Option fail, no option passed): https://gist.github.com/Blaisorblade/6529621 Am I doing something wrong there, or should I open an issue? Does it work for you? – Blaisorblade Sep 11 '13 at 20:58
  • Yes, it works for me. You might a) look at the pom in your .ivy2/cache and verify it has `info.apiURL` b) look at `show compile:doc:apiMappings`, which should have the Map of `File->URL` passed in `doc` c) look at `show compile:doc::autoApiMappings` to verify that is enabled. d) look at `about` to verify the sbt and Scala versions being used. e) check that `~/.sbt/0.13/` doesn't have anything set. – Mark Harrah Sep 11 '13 at 21:09
  • 1
    @MarkHarrah: I figured out the problem: downloading scala-library with 0.12.4 (or .x I guess) will create a bad ivy descriptor. (a) was the problem: SBT 0.12.4 doesn't generate enough metadata in the ivy file (not the POM, I didn't find any in the Ivy cache - and the POM is OK). This was reflected in `apiMappings` being empty while the rest was fine. The Ivy file contained mention of info.apiUrl, but only in a different tag. All data is available at https://github.com/Blaisorblade/sbt-test-case-apiUrl, instructions to reproduce are in the last commit. And clean+update on 0.13 is no fix. – Blaisorblade Sep 11 '13 at 23:03
  • That's disappointing and will be a common problem. Only 0.13 knows that the `info.apiURL` property is important and should be made into an extra attribute. Clean `~/.ivy2/cache/org.scala-lang/scala-library/ivy-2.10.2.xml`. Please open a bug. I'm not sure it can be worked around, but we'll see. – Mark Harrah Sep 12 '13 at 12:51

2 Answers2

7

I know no solution for autoAPIMappings, but here are some alternatives.

  1. A possible alternative, using 0.13's apiMappings, one can setup a manual mapping. On my system, last doc shows that this adds -doc-external-doc:/Users/pgiarrusso/.sbt/boot/scala-2.10.2/lib/scala-library.jar#http://www.scala-lang.org/api/2.10.2/ to the command line, and it works.

    apiMappings += (scalaInstance.value.libraryJar -> url(s"http://www.scala-lang.org/api/${scalaVersion.value}/"))

This requires Scaladoc 2.10.2 or later.

  1. Alternatively, one can add the same option by hand. This is necessary on SBT 0.12. The main nontrivial step is to find the right library.

    In 0.13 syntax:

    scalacOptions in (Compile, doc) += s"-doc-external-doc:${scalaInstance.value.libraryJar}#http://www.scala-lang.org/api/${scalaVersion.value}/"

    In 0.12 syntax:

    scalacOptions in (Compile, doc) <+= (scalaVersion, scalaInstance) map { (scalaVer, scalaIn) =>
  "-doc-external-doc:" + scalaIn.libraryJar + "#http://www.scala-lang.org/api/" + scalaVer + "/"}

    This option still requires Scaladoc 2.10.2.

  2. Finally, on older Scaladocs one can use -external-urls, even though it is less precise (and thus deprecated), as @MarkHarrah had suggested earlier.

    In 0.13 syntax:

    scalacOptions in (Compile, doc) += s"-external-urls:scala=http://www.scala-lang.org/api/${scalaVersion.value}/"

    In 0.12 syntax:

    scalacOptions in (Compile, doc) <+= scalaVersion map (scalaVer => "-external-urls:scala=http://www.scala-lang.org/api/" + scalaVer + "/")

Finally, note that in all cases occurrences of String do not become a hyperlink, maybe because of some bug with type aliases. However, other types (including GenTraversable) are hyperlinked.

Community
  • 1
  • 1
Blaisorblade
  • 6,438
  • 1
  • 43
  • 76
3

Simply use this plugin:

https://github.com/ThoughtWorksInc/sbt-api-mappings

And the external references will be resolved.

Yang Bo
  • 3,586
  • 3
  • 22
  • 35