API documentation

Scaladoc

To include Scaladoc with your site, add the following line to your build.sbt:

copysourceenablePlugins(SiteScaladocPlugin)

This will default to putting the Scaladoc under the latest/api directory on the website. You can change this with the siteSubdirName key in the SiteScaladoc scope:

copysource// Puts Scaladoc output in `target/site/api/latest`
SiteScaladoc / siteSubdirName := "api/latest"

Aggregating API documentation with sbt-unidoc

sbt-unidoc allows to aggregate Scaladoc or Javadoc from sub-projects into a unified view. The following example shows how you can add aggregated Scaladoc to your site:

copysourcelazy val cats = project.in(file("cats"))
lazy val kittens = project.in(file("kittens")).dependsOn(cats)

lazy val root = project.in(file("."))
  .settings(
    ScalaUnidoc / siteSubdirName := "api",
    addMappingsToSiteDir(ScalaUnidoc / packageDoc / mappings, ScalaUnidoc / siteSubdirName)
  )
  .enablePlugins(ScalaUnidocPlugin)
  .aggregate(cats, kittens)

Scaladoc from multiple projects

In case you want to include the Scaladoc separate for each sub-product there are several options. If you only have a few sub-projects the simplest solution is to manually include the scaladoc for each project:

copysourcelazy val cats = project.in(file("cats"))
lazy val kittens = project.in(file("kittens")).dependsOn(cats)

// Define a `Configuration` for each project.
val Cats = config("cats")
val Kittens = config("kittens")

lazy val siteWithScaladoc = project.in(file("site/scaladoc"))
  .settings(
    SiteScaladocPlugin.scaladocSettings(Cats, cats / Compile / packageDoc / mappings, "api/cats"),
    SiteScaladocPlugin.scaladocSettings(Kittens, kittens / Compile / packageDoc / mappings, "api/kittens")
  )

For projects with many such sub-projects, a more maintainable approach is to configure it in a more programatic way:

copysourcelazy val cats = project.in(file("cats"))
lazy val kittens = project.in(file("kittens")).dependsOn(cats)

lazy val scaladocSiteProjects = List((cats, Cats), (kittens, Kittens))

lazy val scaladocSiteSettings = scaladocSiteProjects.flatMap { case (project, conf) =>
  SiteScaladocPlugin.scaladocSettings(
    conf,
    project / Compile / packageDoc / mappings,
    s"api/${project.id}"
  )
}

val siteWithScaladocAlt = project.in(file("site/scaladoc-alternative"))
  .settings(scaladocSiteSettings)