禁用 sbt 子项目文档生成 [英] Disable sbt subproject doc generation

问题描述

我在 SBT 中有一个多项目 Scala 构建，其中我有一个根项目，它有效地聚合了两个子项目:一个宏库和一个使用该宏库的核心库.

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.

我正在使用出色的 sbt-unidoc 插件来为整个库(宏 + 核心组合)创建一个统一的 scaladoc API.

I'm using the excellent sbt-unidoc plugin to create a single, unified scaladoc API for the entire library (macro + core combined).

不幸的是，sbt-unidoc 有一些限制.例如，默认情况下，它不会挂接到 doc 任务中，它的输出放在目标目录的 unidoc 文件夹中，而不是 api文件夹.结合起来，这些可以防止在执行 publish 或 publishLocal 命令时生成和打包生成的文档.幸运的是(感谢 an issue 由 inkytonic 提出在 sbt-unidoc GitHub 站点上)，有一个简单的解决方案:

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)

现在，如果您执行 sbt 任务 doc、publish、publishLocal 等，root 项目将为两个子项目生成统一的文档，统一的文档在发布时打包.

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.

不幸的是，这些相同的命令还尝试为 macro 和 core 子项目生成单独的子项目 API 文档 - 而且，在我的特定情况下，出于各种原因，这些都会失败.更不用说两次生成文档需要时间.

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.

那么，我的问题是:有没有什么简单的方法可以禁用每个子项目的 doc 任务?

So, here's my question: is there any simple way to disable the doc task for each subproject?

到目前为止，我能发现的唯一方法是让 doc 认为没有嵌入 Scaladoc 的文件.这行得通，但它是一种糊涂，而不是真正的解决方案:

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 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)

应该可以，我相信.

这篇关于禁用 sbt 子项目文档生成的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！