Scala/SBT: How to generate project API documentation

This is an excerpt from the Scala Cookbook (partially modified for the internet). This is Recipe 18.8, “Generating SBT Project API Documentation.”

Problem

In an SBT project, you’ve marked up your Scala source code with Scaladoc comments, and want to generate the API documentation for your project.

Solution

Use any of the SBT commands listed in the following table, depending on your documentation needs.

SBT Command Description
doc Creates Scaladoc API documentation from the Scala source code files located in src/main/scala.
test:doc Creates Scaladoc API documentation from the Scala source code files located in src/test/scala.
package-doc Creates a JAR file containing the API documentation created from the Scala source code in src/main/scala.
test:package-doc Creates a JAR file containing the API documentation created from the Scala source code in src/test/scala.
publish Publishes artifacts to the repository defined by the publish-to setting. See Recipe 18.15, “Publishing Your Library.”
publish-local Publishes artifacts to the local Ivy repository as described. See Recipe 18.15, “Publishing Your Library.”

For example, to generate API documentation, use the doc command:

$ sbt doc

At the time of this writing, SBT doesn’t show where the output from this command is written to, but with Scala 2.10.0, SBT 0.12.3 places the root index.html Scaladoc file at target/scala-2.10/api/index.html under the root directory of your project. Other commands, including package-doc and publish, do indicate where their output is located.

The following example shows that publish-local generates its output for a project named “Hello” to the .ivy2 directory under your $HOME directory:

> sbt publish-local
[info] Loading global plugins from /Users/Al/.sbt/plugins
$HOME/.ivy2/local/hello/hello_2.10/1.0/poms/hello_2.10.pom
$HOME/.ivy2/local/hello/hello_2.10/1.0/jars/hello_2.10.jar
$HOME/.ivy2/local/hello/hello_2.10/1.0/srcs/hello_2.10-sources.jar
$HOME/.ivy2/local/hello/hello_2.10/1.0/docs/hello_2.10-javadoc.jar
$HOME/.ivy2/local/hello/hello_2.10/1.0/ivys/ivy.xml

See Recipe 18.15, “Publishing Your Library,” for examples of how to use publish and publish-local.

For a detailed example of how to use Scaladoc, see Recipe 14.8, “Generating Documentation with Scaladoc.”

See Also

  • The SBT Command Line Reference has more information on these commands
  • When writing Scaladoc, you can use a Wiki-like syntax
  • The Scaladoc tags (@see, @param, etc.) are listed here
  • Recipe 14.8, “Generating Documentation with Scaladoc,” provides more examples of the documentation publishing commands
  • See Recipe 18.15, “Publishing Your Project,” for examples of using publish and publish-local