sbt-unidoc — how to exclude a sub-module from a Ro

2019-07-30 16:55发布

问题:

I am building compound API docs using the sbt-unidoc plugin. I am linking to various projects on GitHub using sbt's RootProject constructor with URIs.

One of these projects has mutually exclusive sub-projects:

val foo = RootProject(uri("git://github.com/Foo/Bar.git#v1.0.0"))

That is, in this project foo, there are two sub-modules foo-db1 and foo-db2, which contain the same types but are built against different dependency library versions.

Now when I try to run unidoc, it fails because a type is defined twice from unidoc's perspective. From the documentation, I can see there is a filter function:

unidocProjectFilter in (ScalaUnidoc, unidoc) := inAnyProject -- inProjects(app)

But how do I create an identifier for a sub-module from my RootProject? In other words, how would I do this:

unidocProjectFilter in (ScalaUnidoc, unidoc) := inAnyProject --
  inProjects(foo).SELECT_SUB_PROJECT(foo-v1)

?

回答1:

The answer is found in this entry: Instead of using RootProject, one creates a number of ProjectRef instances.

import UnidocKeys._

val fooURI = uri("git://github.com/Foo/Bar.git#v1.0.0")
val fooDb1 = ProjectRef(fooURI, "foo-db1") // sub-module I don't want
val fooDb2 = ProjectRef(fooURI, "foo-db2") // sub-module I want

val root = (project in file("."))
  .settings( ... )
  .settings(unidocSettings: _*)
  .settings(site.settings ++ ghpages.settings: _*)
  .settings(
    unidocProjectFilter in (ScalaUnidoc, unidoc) := 
      inAnyProject -- inProjects(fooDb1)
  )
  .aggregate(fooDb2)

Note that putting only fooDb2 in the aggregate and leaving fooDb1 out, does not have any effect. It seems that unidoc always includes all sub-modules, no matter, so one has to use the unidocProjectFilter to explicitly remove projects, even if they don't appear in the aggregate.



标签: scala sbt