feat: add task to aggregate subprojects scaladocs

README.md

@@ -1,11 +1,15 @@
 # Gradle Scala Extras
 
+![CI/CD](https://github.com/tassiluca/gradle-scala-extras/actions/workflows/ci-cd.yaml/badge.svg)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
 This Gradle plugin aims to enhance the Scala Gradle core plugin with quality assurance tools and custom configurations.
 
 ## Features
 
 - Support for [Scalafix](https://scalacenter.github.io/scalafix/) and [Scalafmt](https://scalameta.org/scalafmt/) with a default configuration that can be overridden following the [How to use](#how-to-use) section.
 - Aggressive Scala compiler option to treat warnings as errors is applied by default (still configurable).
+- Out-of-the-box configuration to generate aggregated subprojects scaladoc.
 
 Other features may come in the future.
 
@@ -37,3 +41,7 @@ scalaExtras {
 - `configFile` is a string that allows to set the path to the Scalafix / Scalafmt configuration file;
   - if not set, the plugin will search for a `.scalafix.conf` / `.scalafmt.conf` file in the project root directory. If not found, the default configuration is applied;
   - Default configurations can be found [here](./src/main/resources/io/github/tassiluca/scalaextras/).
+
+Moreover, the plugin adds the following tasks to the project:
+- `format` to automatically format the Scala source code adhering to the QA supported tools;
+- `aggregateScaladoc` to generate the aggregated scaladoc for all the subprojects, including the root one. Generated documentation is placed in the root project `build/docs/aggregated-scaladoc` directory.

src/main/kotlin/io/github/tassiluca/scalaextras/ScalaExtrasPlugin.kt

@@ -8,8 +8,11 @@ import io.github.tassiluca.scalaextras.ScalaCompilerOptions.FAIL_ON_WARNINGS
 import org.gradle.api.Plugin
 import org.gradle.api.Project
 import org.gradle.api.Task
+import org.gradle.api.plugins.JavaBasePlugin
+import org.gradle.api.tasks.SourceSetContainer
 import org.gradle.api.tasks.TaskProvider
 import org.gradle.api.tasks.scala.ScalaCompile
+import org.gradle.api.tasks.scala.ScalaDoc
 import cz.augi.gradle.scalafmt.PluginExtension as ScalafmtExtension
 
 /** The scala extras plugin entry point. */
@@ -25,6 +28,7 @@ class ScalaExtrasPlugin : Plugin<Project> {
         project.configureScalafix(extension.qa.scalafixConfiguration)
         project.configureFormatTask()
         project.configureCompilerOptions(extension)
+        project.configureAggregateScaladocTask()
     }
 
     private fun Project.configureScalaFmt(configuration: ScalafmtConfiguration) {
@@ -73,6 +77,23 @@ class ScalaExtrasPlugin : Plugin<Project> {
         }
     }
 
+    private fun Project.configureAggregateScaladocTask() = tasks.apply {
+        register("aggregateScaladoc", ScalaDoc::class.java) {
+            it.group = JavaBasePlugin.DOCUMENTATION_GROUP
+            it.description = "Aggregate scaladocs from all sub-projects."
+            it.destinationDir = layout.buildDirectory.dir("docs/aggregated-scaladoc").get().asFile
+            it.title = "${project.name} $version API"
+            subprojects.map { proj -> proj.tasks.getByName("compileScala").outputs }.run {
+                it.compilationOutputs.from(this)
+            }
+            subprojects.flatMap { proj ->
+                proj.extensions.getByType(SourceSetContainer::class.java)
+                    .filter { sourceSet -> sourceSet.name == "main" }
+                    .map { sourceSet -> sourceSet.allSource }
+            }.run { it.source(this) }
+        }
+    }
+
     private companion object {
         private const val SCALAFIX_TASK = "scalafix"
         private const val SCALAFMT_TASK = "scalafmtAll"

src/test/kotlin/io/github/tassiluca/scalaextras/ScalaExtrasPluginTest.kt

@@ -35,6 +35,10 @@ class ScalaExtrasPluginTest : FreeSpec({
         "with scala coverage" {
             Testkit.projectTest("scoverage")
         }
+
+        "with aggregate scaladoc" {
+            Testkit.projectTest("aggregated-scaladoc")
+        }
     }
 }) {
     companion object {

src/test/resources/io/github/tassiluca/scalaextras/aggregated-scaladoc/build.gradle.kts

@@ -0,0 +1,17 @@
+plugins {
+    scala
+    id("io.github.tassiluca.gradle-scala-extras")
+}
+
+allprojects {
+    apply(plugin = "scala")
+    apply(plugin = "io.github.tassiluca.gradle-scala-extras")
+
+    repositories {
+        mavenCentral()
+    }
+
+    dependencies {
+        implementation("org.scala-lang:scala3-library_3:3.6.1")
+    }
+}

src/test/resources/io/github/tassiluca/scalaextras/aggregated-scaladoc/core/src/main/scala/io.github.tassiluca/Launcher.scala

@@ -0,0 +1,6 @@
+package io.github.tassiluca
+
+/** A simple object that prints "Hello, world!" to the console. */
+object Launcher:
+  def main(args: Array[String]): Unit =
+    println("Hello, world!")

src/test/resources/io/github/tassiluca/scalaextras/aggregated-scaladoc/settings.gradle.kts

@@ -0,0 +1,4 @@
+include(
+    "core",
+    "utils",
+)

src/test/resources/io/github/tassiluca/scalaextras/aggregated-scaladoc/test.yaml

@@ -0,0 +1,20 @@
+tests:
+  - description: "Properly formatted sources"
+    configuration:
+      tasks:
+        - clean
+        - check
+        - aggregateScaladoc
+      options:
+        - --stacktrace
+        - --info
+    expectation:
+      result: success
+      outcomes:
+        success:
+          - check
+          - aggregateScaladoc
+      files:
+        existing:
+          - name: "build/docs/aggregated-scaladoc/io/github/tassiluca/Launcher$.html"
+          - name: "build/docs/aggregated-scaladoc/io/github/tassiluca/Square.html"

src/test/resources/io/github/tassiluca/scalaextras/aggregated-scaladoc/utils/src/main/scala/io.github.tassiluca/Square.scala

@@ -0,0 +1,15 @@
+package io.github.tassiluca
+
+/** A square class that takes a side and calculates the area and perimeter
+  * @param side the side of the square
+  */
+case class Square(side: Double):
+  /** Calculates the area of the square
+    * @return the area of the square
+    */
+  def area: Double = side * side
+
+  /** Calculates the perimeter of the square
+    * @return the perimeter of the square
+    */
+  def perimeter: Double = 4 * side