8

我目前正在编写用 Scala 编写的 API 的文档。我想包括几个图表以使代码更易于理解。

我想知道将资源（例如图表）放在哪里，以便可以通过调用 scaladoc 自动导入它们，以及如何在代码文档中引用这些资源。

例如，假设我使用 sbt。我的代码位于src/main/scala目录中。以下是 package 的 scala 包对象示例foo：

/**
 * Provides main classes of the bar API.
 *
 * ==Overview==
 * Main classes are depicted on the following diagram:
 * <img src="path/to/diagram-foo.svg" />
 *
 */
package object foo {
}

'diagram-foo.svg' 应该位于我的项目中的哪个位置以便对 scaladoc 可见？随后，标签path/to/中的正确值是什么？img

4

2 回答 2

10

警告这可能是一个黑客，因为我对 scaladoc 知之甚少。

由于<img src="../path/to/diagram-foo.svg" />只是一个常规的 HTML，您只需将必要的资产复制到 doc 目标路径即可img解析。

您可以使用以下copyDocAssetsTask自定义任务，该任务与(doc in Compile)目录一起src/main/doc-resources为您提供所需的内容。关键是将图像复制到生成文档的目录，即(target in (Compile, doc)).value.

构建.sbt：

lazy val copyDocAssetsTask = taskKey[Unit]("Copy doc assets")

copyDocAssetsTask := {
  println("Copying doc assets")
  val sourceDir = file("src/main/doc-resources")
  val targetDir = (target in (Compile, doc)).value
  IO.copyDirectory(sourceDir, targetDir)
}

copyDocAssetsTask <<= copyDocAssetsTask triggeredBy (doc in Compile)

显然，您放置图像的目录是任意的，当您做出其他决定时，只需相应地更新自定义任务。

于 2014-06-14T22:44:30.423 回答
3

谢谢，我对此进行了改编，希望对其他人有所帮助，尤其是在多模块项目中：

首先，https: //github.com/sbt/sbt-unidoc 上的 unidoc 会将您的 scaladoc 从多模块项目合并到一个位置，这通常是您想要的。然后 build.sbt 中的以下内容：

lazy val copyDocAssetsTask = taskKey[Unit]("Copy unidoc resources")

copyDocAssetsTask := {
  println("Copying unidoc resources")
  val sourceDir = file("src/main/doc-resources")
  val targetDir = (target in (Compile, doc)).value.getParentFile
  println(s"from ${sourceDir.getAbsolutePath} to ${targetDir.getAbsolutePath}")
  IO.copyDirectory(sourceDir, new java.io.File(targetDir, "unidoc"))
}

copyDocAssetsTask := (copyDocAssetsTask triggeredBy (unidoc in Compile)).value

然后将您的文档放在src/main/doc-resources 根项目中的子目录中，在您的包结构之后的子目录中，以便使用 scaladoc 包含图表（这只是让您不必在 URL 中弄乱父目录）并嵌入类似的东西：

<img src="DesignModel.svg" width="98%"/>在你的 scaladoc

例如，如果此 scaladoc 位于com.someone.thing多模块构建中任何项目的包中的类中，则该DesignModel.svg文件将进入src/main/doc-resources/com/someone/thing根项目中。

于 2018-02-09T15:44:22.347 回答