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?

Exasperate

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.

Expellant

This works, even though not built-in with scaladoc. Thank you! – Exasperate

Great! We're both learning sbt! Please accept the answer when time permits. Thanks! – Expellant

Answer 2

Thanks, I used an adaptation of this that I hope might help others, particularly on multi-module projects:

First, unidoc at https://github.com/sbt/sbt-unidoc will merge your scaladoc from multi-module projects into a single location, which is typically what you want. Then the following in 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

then put your documents under src/main/doc-resources in the root project in subdirectories following your package structure for the path to your class with the scaladoc to include the diagram (this just saves you having to mess around with parent directories in the URL) and embed something like:

<img src="DesignModel.svg" width="98%"/> in your scaladoc

e.g. if this scaladoc was in a class in package com.someone.thing in any project in the multi-module build, the DesignModel.svg file would go in src/main/doc-resources/com/someone/thing inside the root project.

Estonian