spring-framework/gradle/docs.gradle

/*
 * Copyright 2002-2019 the original author or authors.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *       https://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

task api(type: Javadoc) {
	group = "Documentation"
	description = "Generates aggregated Javadoc API documentation."
	title = "${rootProject.description} ${version} API"

	dependsOn {
		subprojects.collect {
			it.tasks.getByName("jar")
		}
	}
	options.encoding = "UTF-8"
	options.memberLevel = org.gradle.external.javadoc.JavadocMemberLevel.PROTECTED
	options.author = true
	options.header = rootProject.description
	options.use = true
	options.overview = "src/docs/api/overview.html"
	options.stylesheetFile = file("src/docs/api/stylesheet.css")
	options.splitIndex = true
	options.links(project.ext.javadocLinks)
	options.addStringOption('Xdoclint:none', '-quiet')

	source subprojects.collect { project ->
		project.sourceSets.main.allJava
	}

	maxMemory = "1024m"
	destinationDir = new File(buildDir, "api")

	doFirst {
		classpath = files(
				// ensure the javadoc process can resolve types compiled from .aj sources
				project(":spring-aspects").sourceSets.main.output
		)
		classpath += files(subprojects.collect { it.sourceSets.main.compileClasspath })
	}
}

dokka {
	dependsOn {
		tasks.getByName("api")
	}
	doFirst {
		classpath = subprojects.collect { project -> project.jar.outputs.files.getFiles() }.flatten()
		classpath += files(subprojects.collect { it.sourceSets.main.compileClasspath })

	}
	moduleName = "spring-framework"
	outputFormat = "html"
	outputDirectory = "$buildDir/docs/kdoc"

	sourceDirs = files(subprojects.collect { project ->
		def kotlinDirs = project.sourceSets.main.kotlin.srcDirs.collect()
		kotlinDirs -= project.sourceSets.main.java.srcDirs
	})
	externalDocumentationLink {
		url = new URL("https://docs.spring.io/spring-framework/docs/$version/javadoc-api/")
		packageListUrl = new File(buildDir, "api/package-list").toURI().toURL()
	}
	externalDocumentationLink {
		url = new URL("https://projectreactor.io/docs/core/release/api/")
	}
	externalDocumentationLink {
		url = new URL("https://www.reactive-streams.org/reactive-streams-1.0.1-javadoc/")
	}
	externalDocumentationLink {
		url = new URL("https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/")
	}
}

configurations {
	docs
}

dependencies {
	// for documentation resources
	docs "io.spring.docresources:spring-doc-resources:0.1.0.RELEASE@zip"
}

task extractDocResources(type: Sync) {
	dependsOn configurations.docs
	from "src/docs/asciidoc/"
	from {
		configurations.docs.collect { zipTree(it) }
	}
	into "$buildDir/asciidoc/build"
}

asciidoctor {
	sourceDir "$buildDir/asciidoc/build"
	sources {
		include '*.adoc'
	}
	resources {
		from(sourceDir) {
			include 'images/*', 'css/**', 'js/**'
		}
	}
	logDocuments = true
	backends = ["html5"]
	// only ouput PDF documentation for non-SNAPSHOT builds
	if(!project.getVersion().toString().contains("BUILD-SNAPSHOT")) {
		backends += "pdf"
	}
	options doctype: 'book', eruby: 'erubis'
	attributes  'icons': 'font',
			'idprefix': '',
			'idseparator': '-',
			docinfo: 'shared',
			revnumber: project.version,
			sectanchors: '',
			sectnums: '',
			'source-highlighter=highlight.js',
			'highlightjsdir=js/highlight',
			'highlightjs-theme=atom-one-dark-reasonable',
			stylesdir: "css/",
			stylesheet: 'stylesheet.css',
			'spring-version': project.version

}

asciidoctor.dependsOn extractDocResources

task docsZip(type: Zip, dependsOn: ['api', 'asciidoctor', 'dokka']) {
	group = "Distribution"
	baseName = "spring-framework"
	classifier = "docs"
	description = "Builds -${classifier} archive containing api and reference " +
			"for deployment at https://docs.spring.io/spring-framework/docs."

	from("src/dist") {
		include "changelog.txt"
	}

	from (api) {
		into "javadoc-api"
	}

	from ("$asciidoctor.outputDir/html5") {
		into "spring-framework-reference"
	}

	from ("$asciidoctor.outputDir/pdf") {
		into "spring-framework-reference/pdf"
	}

	from (dokka) {
		into "kdoc-api"
	}
}

task schemaZip(type: Zip) {
	group = "Distribution"
	baseName = "spring-framework"
	classifier = "schema"
	description = "Builds -${classifier} archive containing all " +
			"XSDs for deployment at https://springframework.org/schema."
	duplicatesStrategy 'exclude'
	moduleProjects.each { subproject ->
		def Properties schemas = new Properties();

		subproject.sourceSets.main.resources.find {
			it.path.endsWith("META-INF/spring.schemas")
		}?.withInputStream { schemas.load(it) }

		for (def key : schemas.keySet()) {
			def shortName = key.replaceAll(/http.*schema.(.*).spring-.*/, '$1')
			assert shortName != key
			File xsdFile = subproject.sourceSets.main.resources.find {
				it.path.endsWith(schemas.get(key))
			}
			assert xsdFile != null
			into (shortName) {
				from xsdFile.path
			}
		}
	}
}

task distZip(type: Zip, dependsOn: [docsZip, schemaZip]) {

	group = "Distribution"
	baseName = "spring-framework"
	classifier = "dist"
	description = "Builds -${classifier} archive, containing all jars and docs, " +
			"suitable for community download page."

	ext.baseDir = "${baseName}-${project.version}";

	from("src/docs/dist") {
		include "readme.txt"
		include "license.txt"
		include "notice.txt"
		into "${baseDir}"
		expand(copyright: new Date().format("yyyy"), version: project.version)
	}

	from(zipTree(docsZip.archivePath)) {
		into "${baseDir}/docs"
	}

	from(zipTree(schemaZip.archivePath)) {
		into "${baseDir}/schema"
	}

	moduleProjects.each { subproject ->
		into ("${baseDir}/libs") {
			from subproject.jar
			if (subproject.tasks.findByPath("sourcesJar")) {
				from subproject.sourcesJar
			}
			if (subproject.tasks.findByPath("javadocJar")) {
				from subproject.javadocJar
			}
		}
	}
}

distZip.mustRunAfter subprojects.test

// Create a distribution that contains all dependencies (required and optional).
// Not published by default; only for use when building from source.
task depsZip(type: Zip, dependsOn: distZip) { zipTask ->
	group = "Distribution"
	baseName = "spring-framework"
	classifier = "dist-with-deps"
	description = "Builds -${classifier} archive, containing everything " +
			"in the -${distZip.classifier} archive plus all runtime dependencies."

	from zipTree(distZip.archivePath)

	gradle.taskGraph.whenReady { taskGraph ->
		if (taskGraph.hasTask(":${zipTask.name}")) {
			def projectNames = rootProject.subprojects*.name
			def artifacts = new HashSet()
			subprojects.each { subproject ->
				(subproject.configurations.runtime.resolvedConfiguration.resolvedArtifacts +
						subproject.configurations.optional.resolvedConfiguration.resolvedArtifacts).each { artifact ->
					def dependency = artifact.moduleVersion.id
					if (!projectNames.contains(dependency.name)) {
						artifacts << artifact.file
					}
				}
			}

			zipTask.from(artifacts) {
				into "${distZip.baseDir}/deps"
			}
		}
	}
}