Question

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

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

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

/**
 * 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 {
}

在哪里＆＃39; diagram-foo.svg＆＃39;位于我的项目中以便scaladoc可见？随后，path/to/代码中img的正确值是什么？

Answer 1

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

由于<img src="../path/to/diagram-foo.svg" />只是常规HTML，您只需将必要的资源复制到文档目标路径，以便img解析。

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

<强> build.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)

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

Answer 2

谢谢，我使用了这个改编，我希望可以帮助其他人，特别是在多模块项目上：

首先，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中的父目录并嵌入类似的东西：

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

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

放置资源的位置，例如图像，scaladoc可以使用？

2 个答案: