hibernate-orm/documentation/documentation.gradle

import org.asciidoctor.gradle.jvm.AsciidoctorTask

plugins {
	id 'org.asciidoctor.jvm.convert' version '3.1.0'
}

/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
 * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
 */

def projectsToIncludeInAggregatedJavadoc = [
		':hibernate-core',
		':hibernate-testing',
		':hibernate-envers',
		':hibernate-agroal',
		':hibernate-c3p0',
		':hibernate-graalvm',
		':hibernate-hikaricp',
		':hibernate-jcache',
		':hibernate-micrometer',
		':hibernate-proxool',
		':hibernate-vibur',
		':hibernate-gradle-plugin',
		':hibernate-enhance-maven-plugin',
		':hibernate-jpamodelgen',
]

projectsToIncludeInAggregatedJavadoc.each {projectPath ->
	evaluationDependsOn projectPath
}

apply from: rootProject.file( 'gradle/java-module.gradle' )
apply plugin: 'org.hibernate.matrix-test'

tasks.build.dependsOn 'buildDocs'
defaultTasks 'buildDocs'


dependencies {
	ext.pressgangVersion = '3.0.0'

	implementation project( ':hibernate-core' )

	annotationProcessor project( ':hibernate-jpamodelgen' )

	testImplementation project(':hibernate-testing')
	testImplementation project(':hibernate-envers')
	// todo (6.0) - add back hibernate-spatial dependency
	//testImplementation project(':hibernate-spatial')
	testImplementation project( ':hibernate-jcache' )
	testImplementation libraries.jcache
	testImplementation project( path: ':hibernate-core', configuration: 'tests' )

	testImplementation 'org.apache.commons:commons-lang3:3.4'
	testImplementation 'org.osgi:org.osgi.core:4.3.1'

	testImplementation libraries.mockito
	testImplementation libraries.mockito_inline

	testRuntimeOnly libraries.wildfly_transaction_client
	testRuntimeOnly libraries.ehcache3
}


if ( project.ormVersion.isSnapshot ) {
	// only run the ci build tasks for SNAPSHOT versions
	task ciBuild( dependsOn: [clean, test] )
}
else {
	task release( dependsOn: [clean, test] )
}

//tasks.test.include 'org/hibernate/'

// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// grouping tasks - declaration, see below for task dependency definitions
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

task buildDocs {
	group 'Documentation'
	description 'Grouping task for performing all documentation building tasks'
}

task buildDocsForPublishing {
	group 'Documentation'
	description 'Grouping task for building all documentation for publishing (release)'
}


// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// aggregated JavaDoc
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

final File javadocDir = mkdir( new File( (File) project.buildDir, 'javadocs' ) );

/**
 * Builds the JavaDocs aggregated (unified) across all the sub-projects
 */
task aggregateJavadocs(type: Javadoc) {
    description = 'Builds an aggregated JavaDoc across all ORM sub-projects'

    final int currentYear = new GregorianCalendar().get( Calendar.YEAR )

    // exclude any generated sources and internal packages
    exclude( '**/generated-src/**' )
    exclude( '**/internal/**' )


	// apply standard config
	maxMemory = '512m'
	destinationDir = javadocDir
	configure( options ) {
		overview = project.file( 'src/main/javadoc/overview.html' )
		windowTitle = 'Hibernate JavaDocs'
		docTitle = "Hibernate JavaDoc ($project.version)"
		bottom = "Copyright &copy; 2001-$currentYear <a href=\"https://redhat.com\">Red Hat, Inc.</a>  All Rights Reserved."
		use = true
		options.encoding = 'UTF-8'

		links = [
				'https://docs.oracle.com/javase/8/docs/api/',
				'https://docs.jboss.org/hibernate/beanvalidation/spec/2.0/api/',
				'https://docs.jboss.org/cdi/api/2.0/',
				'https://javaee.github.io/javaee-spec/javadocs/'
		]
		
		if ( gradle.ext.javaVersions.main.compiler.asInt() >= 11 ) {
			//The need to set `--source 1.8` applies to all JVMs after 11, and also to 11
			// but after excluding the first two builds; see also specific comments on
			// https://bugs.openjdk.java.net/browse/JDK-8212233?focusedCommentId=14245762
			// For now, let's be compatible with JDK 11.0.3+. We can improve on it if people
			// complain they cannot build with JDK 11.0.0, 11.0.1 and 11.0.2.
			logger.lifecycle "Forcing Javadoc in Java 8 compatible mode"
			options.source = gradle.ext.baselineJavaVersion
		}

		options.addStringOption( 'Xdoclint:none', '-quiet' )

		if ( gradle.ext.javaToolchainEnabled ) {
			options.setJFlags( getProperty( 'toolchain.javadoc.jvmargs' ).toString().
							split( ' ' ).toList().findAll( { !it.isEmpty() } ) )
		}
	}

	if ( gradle.ext.javaToolchainEnabled ) {
		// Display version of Java tools
		doFirst {
			logger.lifecycle "Aggregating javadoc with '${javadocTool.get().metadata.installationPath}'"
		}
	}

    // process each project, building up:
    //      1) appropriate sources
    //      2) classpath
	projectsToIncludeInAggregatedJavadoc.each {projectPath ->
		def includeProject = parent.project(projectPath)

		// we only care about the main SourceSet...
		source includeProject.sourceSets.main.java
		classpath += ( includeProject.sourceSets.main.output + includeProject.sourceSets.main.compileClasspath )

	}
}


asciidoctorj {
	attributes  icons: 'font',
			experimental: true,
			'source-highlighter': 'prettify',
			majorMinorVersion: rootProject.ormVersion.family,
			fullVersion: rootProject.ormVersion.fullName

	options logDocuments: true
}


// Topical Guides ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

task renderTopicalGuides(type: AsciidoctorTask, group: 'Documentation') {
    description = 'Renders the  Topical Guides in HTML format using Asciidoctor.'

    sourceDir = file( 'src/main/asciidoc/topical' )
	outputDir = new File("$buildDir/asciidoc/topical/html_single")

	baseDirFollowsSourceDir()

	resources {
		from('src/main/asciidoc/topical/') {
			include '**/images/**'
		}
	}

}


// Getting Started Guides (quick starts) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

task renderGettingStartedGuides(type: AsciidoctorTask, group: 'Documentation') {
    description = 'Renders the Getting Started Guides (quick starts) in HTML format using Asciidoctor.'

    sourceDir = file( 'src/main/asciidoc/quickstart/guides' )
    sources {
        include 'index.adoc'
    }
    outputDir = new File("$buildDir/asciidoc/quickstart/html_single")

	baseDirFollowsSourceDir()
}


task buildTutorialZip(type: Zip) {
	from 'src/main/asciidoc/quickstart/tutorials'
	destinationDirectory = tasks.renderGettingStartedGuides.outputDir
	archiveBaseName = 'hibernate-tutorials.zip'
	expand(
			version: project.version,
			slf4j: "1.7.5",
			junit: project.junitVersion,
			h2: project.h2Version
	)
}

renderGettingStartedGuides.dependsOn buildTutorialZip

// User Guide ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

task renderUserGuide(type: AsciidoctorTask, group: 'Documentation') {
    description = 'Renders the User Guides in HTML format using Asciidoctor.'

    sourceDir = file( 'src/main/asciidoc/userguide' )
    sources {
        include 'Hibernate_User_Guide.adoc'
    }
    outputDir = new File("$buildDir/asciidoc/userguide/html_single")

	baseDirFollowsSourceDir()

	attributes linkcss: true,
			   stylesheet: "css/hibernate.css",
			   docinfo: 'private',
			   jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/"

	resources {
        from('src/main/asciidoc/userguide/') {
            include 'images/**'
        }
		from('src/main/style/asciidoctor') {
			include 'images/**'
		}
		from('src/main/style/asciidoctor') {
			include 'css/**'
		}
		from('src/main/style/asciidoctor') {
			include 'js/**'
		}
    }
}

// Integration Guide ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

task renderIntegrationGuide(type: AsciidoctorTask, group: 'Documentation') {
	description = 'Renders the User Guides in HTML format using Asciidoctor.'

	sourceDir = file( 'src/main/asciidoc/integrationguide' )
	sources {
		include 'Hibernate_Integration_Guide.adoc'
	}

	outputDir = new File("$buildDir/asciidoc/integrationguide/html_single")

	baseDirFollowsSourceDir()

	attributes linkcss: true,
				stylesheet: "css/hibernate.css"

	resources {
		from('src/main/asciidoc/integrationguide/') {
			include 'images/**'
		}
		from('src/main/style/asciidoctor') {
			include 'images/**'
		}
		from('src/main/style/asciidoctor') {
			include 'css/**'
		}
	}
}

// Testing

test {
	include '**/mapping/basic/**'
}

// resources inherently exclude sources
sourceSets.test.resources {
	setSrcDirs( ['src/test/java','src/test/resources'] )
}


// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// grouping tasks
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

buildDocs.dependsOn aggregateJavadocs
buildDocs.dependsOn renderTopicalGuides
buildDocs.dependsOn renderGettingStartedGuides
buildDocs.dependsOn renderUserGuide
buildDocs.dependsOn renderIntegrationGuide

buildDocsForPublishing.dependsOn aggregateJavadocs
buildDocsForPublishing.dependsOn renderTopicalGuides
buildDocsForPublishing.dependsOn renderGettingStartedGuides
buildDocsForPublishing.dependsOn renderUserGuide
buildDocsForPublishing.dependsOn renderIntegrationGuide

checkstyleMain.exclude '**/org/hibernate/userguide/model/*'