🐘

【Gradle】JavadocやテストレポートをGitHub Pagesに公開する

に公開
GitHub
Gradle
Java
tech

背景

最近のっぴきならなくもない事情でJavaを触り始めました。
varやStream、switch式を知らなかったので「古臭くて冗長」というイメージでしたが、モダンな書き方もできるんだぜということがわかってきたので、練習も兼ねてテンプレートリテラルっぽく書けるちっこいクラスを作ってみました。

https://github.com/fj68/java-text-template

このプロジェクト（というほど大げさでもないけど）ではJavadocでドキュメントを書き、JUnit 5でテストを走らせているため、それぞれ成果物たるHTMLを適当な場所（build/docs/javadoc/build/reports/tests/test）に出力してくれます。
さて、せっかくAPIドキュメントやテストレポートを生成したのでGitHub Pagesに公開して「それっぽく」したい！と思うのが人情です。
大した手間ではないのですが、Gradleの設定など、情報にたどり着くのに時間がかかったので未来の自分のためにもここに書き残しておきます。

環境

  • Linux Mint 20.3 Una (based on Ubuntu 20.04 Focal Fossa)
  • Oracle Java SE 17.0.3.1
  • Gradle 7.4.2
  • JUnit 5.8.2

なお、残念ながら2022年5月4日現在、GradleはJava 18に未対応です。うにょーん。

Java 18 and later versions are not yet supported.

https://docs.gradle.org/current/userguide/compatibility.html

全体像

  1. gradle javadocでdocs/javadocにドキュメントを生成
  2. gradle testでテストを実行し、docs/test-reportsにレポートを生成
  3. GitHub Pagesを有効にしてmainブランチのdocsディレクトリを公開するように設定する
  4. git pushするとアカウント名.github.io/レポジトリ名/javadoc/やアカウント名.github.io/レポジトリ名/test-reports/が見れるようになる

mainブランチにドキュメント類を置くのはお行儀が悪い！という意見もあります（わかる）。

Javadoc

build.gradleでJavadocの出力先を設定しましょう。

https://docs.gradle.org/current/dsl/org.gradle.api.tasks.javadoc.Javadoc.html#org.gradle.api.tasks.javadoc.Javadoc:destinationDir

reporting.fileだとbuild/docsに出力されてしまうので注意です（たぶんReportingのdocsDirあたりをいじるのが正攻法なのかな〜と思いつつ目をそらす）。

javadoc {
  destinationDir = file("docs/javadoc")
}

gradle javadocするとdocs/javadocに出力されます。

Test

build.gradleでテストレポートの出力先を設定します。

テストレポートはReportingというAPIで制御されているようで、reportsというインスタンスにhtmlやcssなど種別ごとのReportオブジェクトが格納されているようです。

https://docs.gradle.org/current/dsl/org.gradle.api.reporting.Reporting.html

https://docs.gradle.org/current/dsl/org.gradle.api.reporting.Report.html#org.gradle.api.reporting.Report:outputLocation

「destinationは廃止予定なのでoutputLocationを使え」とあります。

test {
  useJUnitPlatform()
  
  reports.html.outputLocation = file("docs/test-reports")
}

gradle testするとテストが実行されてdocs/test-reportsにレポートが出力されます。

GitHub Pages

特に変わったところはなく、レポジトリのSettings -> Pages -> Sourceをmainに -> folderを/docsにして保存すればOKです。

GitHub Actionsの設定すら不要というお手軽さ。

おわり

えっ、終わり！？

というわけでおわりです。
なんて簡単なんだ……

一応、今回はindex.htmlを用意していないのでhttps://アカウント登録.github.io/レポジトリ名/にアクセスしても404になりますので注意してください。
READMEにアカウント名.github.io/レポジトリ名/javadoc/やアカウント名.github.io/レポジトリ名/test-reports/へのリンクを含めておくと親切だと思います。

Discussion