I have a multi-project Scala build in SBT, in which I have a root project that effectively just aggregates two subprojects: a macro library and a core library that uses that macro library.
I'm using the excellent <a href="https://github.com/sbt/sbt-unidoc" rel="nofollow">
sbt-unidoc</a> plugin to create a single, unified
scaladoc API for the entire library (macro + core combined).
sbt-unidoc has some limitations. For instance, by default, it does not hook into the
doc task, and its output is placed in the target directory's
unidoc folder, instead of the
api folder. Combined, these prevent the resulting documentation from being generated and packaged when executing the
publishLocal commands. Fortunately (and thanks to <a href="https://github.com/sbt/sbt-unidoc/issues/2" rel="nofollow">an issue</a> raised by
inkytonic on the
sbt-unidoc <em>GitHub</em> site), there's a simple solution to this:
lazy val customUnidocSettings = unidocSettings ++ Seq ( doc in Compile := (doc in ScalaUnidoc).value, target in unidoc in ScalaUnidoc := crossTarget.value / "api" )
These settings are then employed in the root project:
lazy val macro = (project in file ("macro")). settings ( name = "foo-macro" ) lazy val core = (project in file ("core")). settings ( name = "foo-core" ). dependsOn (macro) lazy val root = (project in file (".")). settings (customUnidocSettings: _*). settings ( name = "foo" ). aggregate (macro, core)
Now, if you execute the sbt tasks
publishLocal, etc. the
root project will generate unified documentation for the two subprojects and that unified documentation is packaged during publication.
Unfortunately, these same commands also attempt to generate individual subproject API documentation for both the
core subprojects - and, for a variety of reasons in my particular case, these will fail. Not to mention that it takes time to generate the documentation twice.
So, here's my question: is there any simple way to disable the
doc task for each subproject?
The only approach I've been able to discover so far is to trick
doc into thinking that there are no files with embedded Scaladoc. This works, but it's a fudge rather than a real solution:
lazy val noDocFileSettings = Seq ( sources in doc in Compile := List() ) lazy val macro = (project in file ("macro")). settings (noDocFileSettings: _*). settings ( name = "foo-macro" ) lazy val core = (project in file ("core")). settings (noDocFileSettings: _*). settings ( name = "foo-core" ). dependsOn (macro)
You can say <a href="http://www.scala-sbt.org/0.13.5/docs/Getting-Started/Multi-Project.html#aggregation" rel="nofollow">exactly what you want to aggregate</a>. In this case
lazy val root = (project in file (".")). settings (customUnidocSettings: _*). settings ( name = "foo", aggregate in doc := false ). aggregate (macro, core)
should work, I believe.