Aggregate javadoc using build-logic (#4457)

* Aggregate javadoc using build-logic

This PR has a few parts to it:
1. Adds a new `build-logic` module to organize our build logic.
2. Adds two convention plugins.
   - `sentry.javadoc` publishes the javadoc
   to a consumable configuration.
   - `sentry.javadoc.aggregate` consumes the published javadoc and
     aggregates them in the root build folder.
3. Deletes the `stylesheet.css`. This was causing the javadoc to look
   unusable. Deleting it fixes this.
4. Each subproject publishes the javadoc to its own subfolder. The
   previous behavior would overwrite the javadoc with each new project
   in the same directory which meant some parts of the javadoc were
   unreachable.

The producer/consumer configuration is based on this blog post: https://www.liutikas.net/2024/12/11/Together-In-Isolation.html
It should be project isolation compatible.

* Ignore `.kotlin` in all directories

* Add back makefile and github workflow

* Address review comments

Author: runningcode

.github/workflows/generate-javadocs.yml

@@ -0,0 +1,34 @@
+name: 'Generate Javadocs'
+on:
+  release:
+    types: [released]
+
+jobs:
+  build-and-deploy-javadocs:
+    name: Build and deploy Javadocs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v4
+        with:
+          submodules: 'recursive'
+
+      - name: set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@8379f6a1328ee0e06e2bb424dadb7b159856a326
+
+      - name: Generate Aggregate Javadocs
+        run: |
+          ./gradlew aggregateJavadocs
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@6c2d9db40f9296374acc17b90404b6e8864128c8 # pin@4.7.3
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: gh-pages
+          FOLDER: build/docs/javadoc
+          CLEAN: true

.gitignore

@@ -20,4 +20,4 @@ distributions/
 sentry-spring-boot-starter-jakarta/src/main/resources/META-INF/spring.factories
 sentry-samples/sentry-samples-spring-boot-jakarta/spy.log
 spy.log
-buildSrc/.kotlin/
+.kotlin

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Fixes
 
 - Send UI Profiling app start chunk when it finishes ([#4423](https://github.com/getsentry/sentry-java/pull/4423))
+- Republish Javadoc [#4457](https://github.com/getsentry/sentry-java/pull/4457)
 
 ## 8.13.2
 

Makefile

@@ -1,6 +1,6 @@
-.PHONY: all clean compile dryRelease update stop checkFormat format api assembleBenchmarkTestRelease assembleUiTestRelease assembleUiTestCriticalRelease createCoverageReports runUiTestCritical check preMerge publish
+.PHONY: all clean compile javadocs dryRelease update stop checkFormat format api assembleBenchmarkTestRelease assembleUiTestRelease assembleUiTestCriticalRelease createCoverageReports runUiTestCritical check preMerge publish
 
-all: stop clean compile createCoverageReports
+all: stop clean javadocs compile createCoverageReports
 assembleBenchmarks: assembleBenchmarkTestRelease
 assembleUiTests: assembleUiTestRelease
 preMerge: check createCoverageReports
@@ -15,9 +15,12 @@ clean:
 compile:
 	./gradlew build
 
+javadocs:
+	./gradlew aggregateJavadocs
+
 # do a dry release (like a local deploy)
 dryRelease:
-	./gradlew distZip --no-build-cache --no-configuration-cache
+	./gradlew aggregateJavadocs distZip --no-build-cache --no-configuration-cache
 
 # check for dependencies update
 update:

build-logic/build.gradle.kts

@@ -0,0 +1,7 @@
+plugins {
+    `kotlin-dsl`
+}
+
+repositories {
+    gradlePluginPortal()
+}

build-logic/settings.gradle.kts

@@ -0,0 +1 @@
+rootProject.name = "build-logic"

build-logic/src/main/kotlin/io.sentry.javadoc.aggregate.gradle.kts

@@ -0,0 +1,29 @@
+import io.sentry.gradle.AggregateJavadoc
+import org.gradle.api.attributes.Category
+import org.gradle.api.attributes.LibraryElements
+import org.gradle.kotlin.dsl.creating
+import org.gradle.kotlin.dsl.getValue
+import org.gradle.kotlin.dsl.named
+
+val javadocPublisher by configurations.creating {
+    isCanBeConsumed = false
+    isCanBeResolved = true
+    attributes {
+        attribute(Category.CATEGORY_ATTRIBUTE, objects.named(Category.DOCUMENTATION))
+        attribute(LibraryElements.LIBRARY_ELEMENTS_ATTRIBUTE, objects.named("javadoc"))
+    }
+}
+
+subprojects {
+    javadocPublisher.dependencies.add(dependencies.create(this))
+}
+
+val javadocCollection = javadocPublisher.incoming.artifactView { lenient(true) }.files
+
+tasks.register("aggregateJavadoc", AggregateJavadoc::class) {
+    group = "documentation"
+    description = "Aggregates Javadocs from all subprojects into a single directory."
+    javadocFiles.set(javadocCollection)
+    rootDir.set(layout.projectDirectory)
+    outputDir.set(layout.buildDirectory.dir("docs/javadoc"))
+}

build-logic/src/main/kotlin/io.sentry.javadoc.gradle.kts

@@ -0,0 +1,27 @@
+val javadocConfig: Configuration by configurations.creating {
+    isCanBeResolved = false
+    isCanBeConsumed = true
+
+    attributes {
+        attribute(Category.CATEGORY_ATTRIBUTE, objects.named(Category.DOCUMENTATION))
+        attribute(LibraryElements.LIBRARY_ELEMENTS_ATTRIBUTE, objects.named("javadoc"))
+    }
+}
+
+tasks.withType<Javadoc>().configureEach {
+    setDestinationDir(project.layout.buildDirectory.file("docs/javadoc").get().asFile)
+    title = "${project.name} $version API"
+    val opts = options as StandardJavadocDocletOptions
+    opts.quiet()
+    opts.encoding = "UTF-8"
+    opts.memberLevel = JavadocMemberLevel.PROTECTED
+    opts.links = listOf(
+        "https://docs.oracle.com/javase/8/docs/api/",
+        "https://docs.spring.io/spring-framework/docs/current/javadoc-api/",
+        "https://docs.spring.io/spring-boot/docs/current/api/"
+    )
+}
+
+artifacts {
+    add(javadocConfig.name, tasks.named("javadoc"))
+}

build-logic/src/main/kotlin/io/sentry/gradle/AggregateJavadoc.kt

@@ -0,0 +1,41 @@
+package io.sentry.gradle
+
+import org.gradle.api.DefaultTask
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.file.FileCollection
+import org.gradle.api.file.FileSystemOperations
+import org.gradle.api.provider.Property
+import org.gradle.api.tasks.InputFiles
+import org.gradle.api.tasks.Internal
+import org.gradle.api.tasks.OutputDirectory
+import org.gradle.api.tasks.TaskAction
+import javax.inject.Inject
+
+abstract class AggregateJavadoc @Inject constructor(
+    @get:Internal val fs: FileSystemOperations
+) : DefaultTask() {
+    @get:InputFiles
+    abstract val javadocFiles: Property<FileCollection>
+
+    // Marked as Internal since this is only used to relativize the paths for the output directories
+    @get:Internal
+    abstract val rootDir: DirectoryProperty
+
+    @get:OutputDirectory
+    abstract val outputDir: DirectoryProperty
+
+    @TaskAction
+    fun aggregate() {
+        javadocFiles.get().forEach { file ->
+            fs.copy {
+                // Get the relative path of the project directory to the root directory
+                val relativePath = file.relativeTo(rootDir.get().asFile)
+                // Remove the 'build/docs/javadoc' part from the path
+                val projectPath = relativePath.path.replace("build/docs/javadoc", "")
+                from(file)
+                // Use the project name as the output directory name so that each javadoc goes into its own directory
+                into(outputDir.get().file(projectPath))
+            }
+        }
+    }
+}

build.gradle.kts

@@ -27,6 +27,7 @@ plugins {
     alias(libs.plugins.errorprone) apply false
     alias(libs.plugins.gradle.versions) apply false
     alias(libs.plugins.spring.dependency.management) apply false
+    id("io.sentry.javadoc.aggregate")
 }
 
 buildscript {
@@ -237,7 +238,7 @@ spotless {
     kotlin {
         target("**/*.kt")
         ktlint()
-        targetExclude("**/sentry-native/**")
+        targetExclude("**/sentry-native/**", "**/build/**")
     }
     kotlinGradle {
         target("**/*.kts")