Where to place resources, e.g. images, that scaladoc can use?

Question

I am currently writing the documentation of an API written in Scala. I would like to include several diagrams to make the code more understandable.

I am wondering where to put resources (such as diagrams) in order that they can be automatically imported by an invocation of scaladoc, and how to refer to these resources in the documentation of the code.

For example, let's assume that I use sbt. My code is located in the src/main/scala directory. Here is an example of a scala package object for package 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 {
}

Where should 'diagram-foo.svg' be located in my project in order to be visible to scaladoc? Subsequently, what is the correct value of path/to/ in the img tag?

Answer 1

WARNING It may be a hack as I know very little about scaladoc.

Since <img src="../path/to/diagram-foo.svg" /> is just a regular HTML you just need to copy necessary assets to the doc target path so the img resolves.

You can use the following copyDocAssetsTask custom task that with (doc in Compile) and src/main/doc-resources directory gives you what you want. The point is to copy images to the directory where the documentation is generated, i.e. (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)

Obviously the directory where you place the images is arbitrary, and when you decide otherwise, just update the custom task accordingly.