Where to place resources, for example. images that scaladoc can use?

Question

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

I’m wondering where to put resources (for example, diagrams) so that they can be automatically imported with a call to scaladoc and how to refer to these resources in the code documentation.

For example, suppose I use sbt. My code is in the src/main/scala directory. The following is an example scala package object for the foo package:

 /** * 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 is the "diagram-foo.svg" located in my project to be visible to scaladoc? Subsequently, what is the correct path/to/ value in the img tag?

Answer 1

WARNING This can be hacked because I know little about skydock.

Since <img src="../path/to/diagram-foo.svg" /> is just plain HTML, you just need to copy the necessary resources to the target path of the dock code to enable img .

You can use the following custom task copyDocAssetsTask , which with the directory (doc in Compile) and src/main/doc-resources gives you what you want. The point is to copy the images to the directory where the documentation is created, 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 in which you place the images is arbitrary, and when you decide otherwise, just update the custom task accordingly.

Answer 2

Thank you, I used an adaptation of this, which I hope can help others, especially in multi-module projects:

Firstly, unidoc at https://github.com/sbt/sbt-unidoc will merge your skydiver from multi-module projects into one place, which is usually what you want, then 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 place your documents under src/main/doc-resources in the root project, in subdirectories following your package structure, for the path to your class using scaladoc to include the diagram (this just eliminates the need to bother with the parent directories in the URL address) and insert something like:

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

eg. if this scaladoc was in the class in the com.someone.thing package in any project in an assembly with several modules, the DesignModel.svg file would be included in src/main/doc-resources/com/someone/thing inside the root project.