Provides means to configure scaladoc settings for sbt.
If one is used to javadoc generation then the scaladoc is a rather different mechanism.
First off there is no overview.html like with javadoc.
One has to specify the path to any root document file using manual settings.
Secondarily there seems to be no way to included static content, such as images.
This plugin will provide the same mechanism as the Javadoc.
Added to that the plugin can also parse PlantUML files and render images out of these.
This can be extremely useful for creating a richer documentation with e.g. class/sequence diagrams.
First off the plugin does expect some standardized layout of the project.
E.g. given below:
[project-root]/
main/
scala/
scaladoc/
doc-files/
flowchart.puml
flowchart.txt
overview.txt
The scaladoc directory maps to the javadoc directory one might be used to from generating Javadoc.
The overview.txt maps to the overview.html used in Javadoc.
This is where you place project root documentation that is not specific to any package.
The doc-files directory is meant for static content such as images and possible static html pages you want to link to.
The files in this directory will automatically be copied to the same output directory of the generated API docs.
With one exception, any files called .puml will be treated as PlantUML files and will automatically be rendered into png images.
This is explained in a later section of the documentation.
This is a fully working example how to add a root file to the doc generation.
E.g.
scalacOptions in (Compile, doc) ++= Seq("-doc-root-content", baseDirectory.value+"/src/main/scaladoc/overview.txt") However to facilitate a common way to manage the overview file one can specify it using ScalaDocSettings.rootDoc.
This will yield the exact same result as the example above, i.e it will expect the file src-dir/main/scaladoc/overview.txt
scalacOptions in (Compile, doc) ++= org.dmonix.sbt.ScalaDocSettings.rootDocShould you want to use some other file then simply specify it using:
scalacOptions in (Compile, doc) ++= org.dmonix.sbt.ScalaDocSettings.rootDoc("yourfilepath")Javadoc has a standard doc-files directory which is automatically included during the javadoc generation.
Thus allowing the documentation author to include static content such as images or even html files.
Scaladoc seems to completely lack this functionality.
This setting overrides the default sequence of files to add in packageDoc.
It's needed in order for the copyDocAssetsTask task to execute.
In practice it will execute the copyDocAssetsTask and add the output to the already generated output by the doc command.
mappings in (Compile, packageDoc) <<= copyDocAssetsTaskAs an addon the plugin manages to automatically render PlantUML diagrams into png files.
This feature is enabled by default and it will automatically convert any .puml files it finds under any doc-files directory.
There's a few configuration options one can set in build.sbt as illustrated below.
If the default values (as below) are ok for you then you don't need to set anything.
processPlantUML := true //default value
plantUMLExtension := ".puml" //default value The output is automatically the name of the puml file where the extension has been changed to .png.
So you can easily refer in to your PlantUML diagrams in your overview.txt file.
There's examples below.
Simply run the packageDoc task to render the documentation.
sbt packageDocThe output should be a jar file containing the documentation.
This means the documentation is also rendered properly when e.g. publishing artifacts using the publish and/or release commands.
###Live Example
Check out the build.sbt for this project to see the usage of the plugin.
Also the overview.txt for an example on how to refer to static files as well as PlantUML images rendered from the plugin.
Simply add this to the plugins.sbt file:
addSbtPlugin("org.dmonix.sbt" % "sbt-scaladoc-settings-plugin" % "0.7")