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
| this post is sponsored by my books: | |||
#1 New Release |
FP Best Seller |
Learn Scala 3 |
Learn FP Fast |
books by alvin
|
|
|
|