标准库的 SBT Scaladoc 配置 [英] SBT Scaladoc configuration for the standard library

问题描述

我想设置 ScalaDoc 以链接到来自 SBT 的标准库.我正在使用 0.12.4，但我很快就会切换到 0.13.此外，我想通过使用 0.13 的支持来简化设置.

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.

最好的选择是使用 0.13 自动映射的 autoAPIMappings:

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

scala-library 应该支持它，因为 它的 pom 设置了 info.apiURL 和 这就是 SBT 读取的内容.

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

然而，这不起作用.String 和 GenTraversable 都没有超链接.last 显示没有选项添加到 scaladoc 参数.

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

所以:

1. 如何修复autoAPIMappings?
2. 有其他选择吗?
3. 我没有观察到此功能有效，但也许我只需要另一个设置 info.apiUrl 的包.有没有想到的包?google 好像没什么用，如何查询具有某些属性的maven 包，甚至如何在poms 上进行全文搜索都不清楚.find ~/.m2 ~/.ivy2 -name '*.pom' -type f|xargs grep info.apiUrl 在我的 2G 本地缓存中没有找到任何结果.

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.

(这个问题可能看起来是 SBT Scaladoc 配置的重复，但它是针对更新的配置和不同的 SBT 版本，所以问题是不同的；而且，现有答案显示了一个已弃用的解决方案).

(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).

推荐答案

我不知道 autoAPIMappings 的解决方案，但这里有一些替代方案.

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

1. 一种可能的替代方法，使用 0.13的apiMappings，可以手动设置映射.在我的系统上，last doc 显示这添加了 -doc-external-doc:/Users/pgiarrusso/.sbt/boot/scala-2.10.2/lib/scala-library.jar#http://www.scala-lang.org/api/2.10.2/ 到命令行，它可以工作.

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

这需要 Scaladoc 2.10.2 或更高版本.

This requires Scaladoc 2.10.2 or later.

1. 或者，您可以手动添加相同的选项.这在 SBT 0.12 上是必需的.主要的重要步骤是找到合适的库.

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.

在 0.13 语法中:

In 0.13 syntax:

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

在 0.12 语法中:

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 + "/"}

此选项仍需要 Scaladoc 2.10.2.

This option still requires Scaladoc 2.10.2.

最后，在较旧的 Scaladocs 上，可以使用 -external-urls，即使它不太精确(因此已弃用)，如 @MarkHarrah 之前已经建议.

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

在 0.13 语法中:

In 0.13 syntax:

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

在 0.12 语法中:

In 0.12 syntax:

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

最后，请注意，在所有情况下，String 的出现都不会成为超链接，这可能是因为某些类型别名的错误.但是，其他类型(包括 GenTraversable)是超链接的.

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.

这篇关于标准库的 SBT Scaladoc 配置的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！