Aggregate Javadoc Gradle Plugin

Provides support for producing an aggregate Javadoc that follows Gradle best practices. This plugin is based on work by jjohannes.

Downloading

Releases are deployed to the Gradle Plugin Portal.

If you are using a SNAPSHOT, first ensure your settings.gradle is updated to resolve plugins from repo.spring.io as shown below:

settings.gradle

pluginManagement {
	repositories {
		gradlePluginPortal()
		maven { url 'https://repo.spring.io/plugins-snapshot' }
	}
}

io.spring.javadoc

Next apply the plugin to each module that should be included in the aggregate Javadoc. The io.spring.javadoc serves as a marker to determine which projects are included in the aggregate Javadoc. As illustrated below, it is also necessary to apply the JavaPlugin to the project.

build.gradle

plugins {
	id 'java-library'
	id 'io.spring.javadoc' version '0.0.1'
}

io.spring.javadoc-aggregate

Next apply the AggregateJavadoc plugin to a project that will produce the aggregate Javadoc.

aggregator/build.gradle

plugins {
	id 'io.spring.javadoc-aggregate' version '0.0.1'
}

aggregateJavadocClasspath Configuration

This will create a Configuration named aggregateJavadocClasspath that is used to determine the classpath for the aggregateJavadoc Task. This Configuration is defaulted to include all projects that have the io.spring.javadoc applied to it.

aggregateJavadoc Task

This will create a task named aggregateJavadoc of type Javadoc. The task defaults the source and classpath to aggregate values based on all of the projects that contain the io.spring.javadoc plugin.

Finally, run the task.

./gradlew :aggregator:aggregateJavadoc

Note	For our example, we assume that io.spring.javadoc-aggregate is applied to the project aggregator. You may apply to any module, but you will need to adjust the task accordingly.

Excluding a Default Project

You can exclude projects that are included by default using Gradle’s build in exclusion mechanism. For example, the following would exclude module2 from being aggregated:

configurations.aggregateJavadocClasspath {
    exclude module: 'module2'
}

Customizing Aggregated Projects

You can customize which projects' Javadoc is aggregated by explicitly providing projects for the aggregateJavadocClasspath configuration. For example, the following explicitly aggregates module1 and module2 regardless of which projects have io.spring.javadoc applied to them.

plugins {
    id 'io.spring.javadoc-aggregate'
}

dependencies {
    aggregateJavadocClasspath project(':module1')
    aggregateJavadocClasspath project(':module3')
}

io.spring.javadoc-conventions

Apply the io.spring.javadoc-conventions plugin to default the Javadoc task options.

The following defaults will be set:

• author is defaulted to true

• docTitle defaulted to a modified value of the root project’s name

  • If it ends in -build, it will be stripped off

  • Any - will be replaced with a space ` `

  • Each word will be capitalized

• encoding is defaulted to UTF-8

• memberLevel is defaulted to JavadocMemberLevel.PROTECTED

• outputLevel is defaulted to JavadocOutputLevel.QUIET

• splitIndex is defaulted to true

• stylesheetFile is defaulted to Spring’s default stylesheet

• use is defaulted to true

• windowTitle is defaulted to the same value as docTitle

License

This project is Open Source software released under the Apache 2.0 license.