Overriding auto API mappings in SBT

Question

I have a few libraries that depend on Cats. Let's say the new Cats 0.4.0 release has the wrong apiURL value in its POM. I don't want my API docs to break, so I provide the URL mapping with apiMappings:

  ..
  autoAPIMappings := false,
  apiMappings ++= (fullClasspath in Compile).value.flatMap(
    entry => entry.get(moduleID.key).map(entry -> _)
  ).collectFirst {
    case (entry, module)
      if module.organization == "org.typelevel" &&
        module.name.startsWith("cats-") =>
          entry.data
  }.map(_ -> url("https://typelevel.org/cats/api/")).toMap,
  apiURL := Some(url("https://travisbrown.github.io/iteratee/api/")),
  ...

This works just fine for links to Cats types in my API docs, but it means that I lose links for types from the standard library and other dependencies. If I change autoAPIMappings to true, though, my custom mapping is gone.

This doesn't make any sense to me—it seems like of course explicitly defined mappings shouldn't be overridden by mappings that are automatically pulled from dependency POMs.

Can I use autoAPIMappings but override it for specific dependencies?

Answer 1

This is probably because apiMappings is redefined for the doc task, and appends mappings when you set autoAPImappings := true, and thus overrides yours, which are defined in the Global scope.

This should work:

apiMappings in doc := ...