sbt-unidoc 使用指南

sbt-unidoc 使用指南

sbt-unidocsbt plugin to create a unified Scaladoc or Javadoc API document across multiple subprojects.项目地址:https://gitcode.com/gh_mirrors/sb/sbt-unidoc

---

项目介绍

sbt-unidoc 是一个为 Scala 和 Java 项目设计的 sbt 插件。它允许开发者在多个子项目中创建统一的 Scaladoc 或 Javadoc API 文档。这个工具特别适用于那些具有复杂结构的项目，其中可能包含了多个相互依赖的子模块。通过 sbbt-unidoc，你可以便捷地合并来自不同部分的文档到一个单一的文档集合，便于团队成员和外部使用者浏览项目整体的API接口。

项目快速启动

要将 sbt-unidoc 应用于你的项目，你需要按照以下步骤操作：

步骤一：添加插件至项目

对于 sbt 1.x 用户（推荐至少使用 sbt 1.5.x）:

// 在 project/plugins.sbt 文件中添加
addSbtPlugin("com.github.sbt" % "sbt-unidoc" % "0.5.0")

对于较旧版本的 sbt，请查阅官方说明或相应兼容版本的文档进行配置。

步骤二：启用插件

在你的 build.sbt 中启用该插件并设置必要参数：

lazy val root = (project in file("."))
  .enablePlugins(ScalaUnidocPlugin)
  .aggregate(library, app) // 假定你有两个子项目 library 和 app
  .settings(name := "我的综合项目")

步骤三：运行 unidoc 任务

完成上述配置后，在项目根目录下执行如下命令来生成统一文档：

sbt unidoc

成功执行后，你将在项目的特定目录（通常是 <crossTarget>/unidoc）找到生成的文档。

应用案例和最佳实践

• 持续集成：将 unidoc 任务整合进你的 CI 流程，确保每次构建后自动更新文档。
• 文档发布：利用 sbt-site 和 sbt-ghpages 将生成的文档部署到 GitHub Pages，提升项目的可访问性和透明度。

// 添加额外的插件以支持网站发布
addSbtPlugin("com.typesafe.sbt" % "sbt-site" % "1.3.2")
addSbtPlugin("com.typesafe.sbt" % "sbt-ghpages" % "0.6.2")

// 配置并发布
import com.typesafe.sbt.SbtGit.GitKeys._
val root = (project in file("."))
  ...
  .settings(GitKeys._)
  .settings(
    ScalaUnidoc / packageDoc / mappings ++= (ScalaUnidoc / unidoc).value,
    // 其他 deploy 到 gh-pages 的相关配置
  )

典型生态项目

虽然本指南专注于 sbt-unidoc，但值得注意的是，在大型企业级开发环境中，此插件常与其他文档管理和自动化工具结合使用，例如 Dokka（用于 Kotlin 项目），以及各种Markdown处理库，用于进一步丰富项目文档。在 Scala 生态系统内，它与 Scalafmt、sbt-header等其他sbt插件共同协作，保持代码风格一致，增强项目的专业性和可维护性。

---

通过遵循这些步骤，你可以轻松地管理多模块项目的文档生成和组织，提高团队的开发效率和项目的可读性。记得适时查看最新版本的插件及其文档，以获得最佳的支持和特性。

sbt-unidocsbt plugin to create a unified Scaladoc or Javadoc API document across multiple subprojects.项目地址:https://gitcode.com/gh_mirrors/sb/sbt-unidoc