Aggregate javadoc using build-logic

.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")