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插件共同协作,保持代码风格一致,增强项目的专业性和可维护性。
通过遵循这些步骤,你可以轻松地管理多模块项目的文档生成和组织,提高团队的开发效率和项目的可读性。记得适时查看最新版本的插件及其文档,以获得最佳的支持和特性。