Disable sbt subproject doc generation

问题

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 sbt-unidoc plugin to create a single, unified scaladoc API for the entire library (macro + core combined).

Unfortunately, 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 publish or publishLocal commands. Fortunately (and thanks to an issue raised by inkytonic on the sbt-unidoc GitHub 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 doc, publish, 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 macro and 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)

Any suggestions?

回答1:

You can say exactly what you want to aggregate. 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.

来源：https://stackoverflow.com/questions/23937344/disable-sbt-subproject-doc-generation

标签

scala

sbt

scaladoc