Skip to content

Commit ce0bf71

Browse files
beikovbeikov
committed
HHH-16962 - General documentation improvements
HHH-17141 - Prepare for 6.3.0 release https://hibernate.atlassian.net/browse/HHH-16962 https://hibernate.atlassian.net/browse/HHH-17141 (cherry picked from commit a2d45a2)
1 parent 9a097e1 commit ce0bf71

File tree

14 files changed

+182
-1394
lines changed

14 files changed

+182
-1394
lines changed

‎documentation/documentation.gradle

Lines changed: 126 additions & 157 deletions
Original file line numberDiff line numberDiff line change
@@ -190,67 +190,53 @@ else {
190190

191191

192192
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
193-
// aggregated JavaDoc
193+
// aggregated Javadoc
194194
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
195195

196-
def aggregateJavadocsTask = tasks.register( "aggregateJavadocs", Javadoc ) {
196+
def aggregateJavadocsTask = tasks.register( "javadoc", Javadoc ) {
197197
group = "documentation"
198-
description = 'Builds an aggregated JavaDoc across all ORM sub-projects'
199-
200-
inputs.property "ormVersion", project.ormVersion
198+
description = 'Builds JavaDoc aggregated across all ORM sub-projects'
201199

202200
destinationDir = mkdir( layout.buildDirectory.file( 'javadocs' ) )
201+
source = configurations.javadocSources
202+
classpath = configurations.javadocClasspath
203203

204-
source configurations.javadocSources
205-
classpath += configurations.javadocClasspath
206-
207-
// exclude any generated sources and internal packages
208-
exclude '**/generated-src/**'
209-
exclude '**/internal/**'
210-
include '**/*.java'
211-
212-
213-
final int currentYear = new GregorianCalendar().get( Calendar.YEAR )
214-
215-
// apply standard config
216-
maxMemory = '512m'
217204
configure( options ) {
218-
overview = 'src/javadoc/overview.html'
219-
stylesheetFile = project.file( 'src/javadoc/stylesheet.css' )
220-
windowTitle = 'Hibernate JavaDocs'
221-
docTitle = "Hibernate JavaDoc ($project.version)"
222-
bottom = "Copyright &copy; 2001-$currentYear <a href=\"https://redhat.com\">Red Hat, Inc.</a> All Rights Reserved."
223-
use = true
224-
options.encoding = 'UTF-8'
225-
226-
links = [
227-
'https://docs.oracle.com/en/java/javase/11/docs/api/',
228-
'https://jakarta.ee/specifications/bean-validation/3.0/apidocs/',
229-
'https://jakarta.ee/specifications/cdi/4.0/apidocs/',
230-
'https://jakarta.ee/specifications/platform/9/apidocs/',
231-
'https://www.javadoc.io/doc/javax.cache/cache-api/1.0.0/'
232-
]
233-
234-
options.addStringOption( 'Xdoclint:none', '-quiet' )
235-
236-
if ( jdkVersions.explicit ) {
237-
options.setJFlags(
238-
getProperty( 'toolchain.javadoc.jvmargs' ).toString().
239-
split( ' ' ).toList().findAll( { !it.isEmpty() } )
240-
)
241-
}
205+
overview = rootProject.file( "shared/javadoc/overview.html" )
206+
windowTitle = 'Hibernate Javadocs'
207+
docTitle = "Hibernate Javadoc ($project.version)"
242208
}
243209

244210
if ( jdkVersions.explicit ) {
211+
// setJFlags(
212+
// getProperty( 'toolchain.javadoc.jvmargs' ).toString().
213+
// split( ' ' ).toList().findAll( { !it.isEmpty() } )
214+
// )
215+
245216
// Display version of Java tools
246217
doFirst {
247218
if ( javadocTool.present ) {
248-
logger.lifecycle "Aggregating javadoc with '${javadocTool.get().metadata.installationPath}'"
219+
logger.lifecycle "Building aggregated javadoc with '${javadocTool.get().metadata.installationPath}'"
249220
}
250221
}
251222
}
223+
224+
doFirst {
225+
def javaLanguageVersion = javadocTool.present
226+
? javadocTool.get().metadata.languageVersion
227+
: JavaLanguageVersion.of( JavaVersion.current().name )
228+
229+
if ( javaLanguageVersion.asInt() > 11 ) {
230+
println "Aggregated Javadocs are bing built` using a JDK newer than version 11: \n" +
231+
"\t* `stylesheet.css` will not be compatible\n" +
232+
"\t* generating the User Guide settings fragment will not succeed"
233+
}
234+
}
252235
}
253236

237+
apply from: rootProject.file( 'gradle/javadoc.gradle' )
238+
239+
254240
asciidoctorj {
255241
requires 'rouge'
256242
modules {
@@ -477,139 +463,122 @@ def renderQueryLanguageGuidesTask = tasks.register( 'renderQueryLanguageGuides'
477463
}
478464

479465

480-
// Introduction ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
481-
482-
tasks.register('renderIntroductionPdf', AsciidoctorPdfTask) {task->
483-
group = "Documentation"
484-
description = 'Renders the Introduction in PDF format using Asciidoctor.'
485-
tasks.buildDocs.dependsOn task
486-
tasks.buildDocsForPublishing.dependsOn task
487-
inputs.property "hibernate-version", project.ormVersion
488-
489-
sourceDir = file( 'src/main/asciidoc/introduction' )
490-
baseDir = file( 'src/main/asciidoc/introduction' )
491-
sources {
492-
include 'Hibernate_Introduction.adoc'
493-
}
494-
outputDir = "$buildDir/asciidoc/introduction/pdf"
495-
496-
attributes jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/"
497-
}
498-
499-
tasks.register('renderIntroduction', AsciidoctorTask) {task->
500-
group = "Documentation"
501-
description = 'Renders the Introduction in HTML format using Asciidoctor.'
502-
tasks.buildDocs.dependsOn task
503-
tasks.buildDocsForPublishing.dependsOn task
504-
inputs.property "hibernate-version", project.ormVersion
505-
506-
sourceDir = file( 'src/main/asciidoc/introduction' )
507-
sources {
508-
include 'Hibernate_Introduction.adoc'
509-
}
510-
outputDir = "$buildDir/asciidoc/introduction/html_single"
511-
512-
attributes linkcss: true,
513-
stylesheet: "css/hibernate.css",
514-
docinfo: 'private',
515-
jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/"
516-
517-
resources {
518-
from('src/main/asciidoc/introduction/') {
519-
include 'images/**'
520-
}
521-
from('src/main/style/asciidoctor') {
522-
include 'images/**'
523-
}
524-
from('src/main/style/asciidoctor') {
525-
include 'css/**'
526-
}
527-
from('src/main/style/asciidoctor') {
528-
include 'js/**'
529-
}
530-
}
531-
}
532-
533-
// HQL Guide ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
534-
535-
tasks.register('renderQLPdf', AsciidoctorPdfTask) {task->
536-
group = "Documentation"
537-
description = 'Renders the Query Language document in PDF format using Asciidoctor.'
538-
tasks.buildDocs.dependsOn task
539-
tasks.buildDocsForPublishing.dependsOn task
540-
inputs.property "hibernate-version", project.ormVersion
541-
542-
sourceDir = file( 'src/main/asciidoc/querylanguage' )
543-
baseDir = file( 'src/main/asciidoc/querylanguage' )
544-
sources {
545-
include 'Hibernate_Query_Language.adoc'
546-
}
547-
outputDir = "$buildDir/asciidoc/querylanguage/pdf"
548-
549-
attributes jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/"
550-
}
551-
552-
tasks.register('renderQL', AsciidoctorTask) {task->
553-
group = "Documentation"
554-
description = 'Renders the Query Language document in HTML format using Asciidoctor.'
555-
tasks.buildDocs.dependsOn task
556-
tasks.buildDocsForPublishing.dependsOn task
557-
inputs.property "hibernate-version", project.ormVersion
558-
559-
sourceDir = file( 'src/main/asciidoc/querylanguage' )
560-
sources {
561-
include 'Hibernate_Query_Language.adoc'
562-
}
563-
outputDir = "$buildDir/asciidoc/querylanguage/html_single"
564-
565-
attributes linkcss: true,
566-
stylesheet: "css/hibernate.css",
567-
docinfo: 'private',
568-
jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/"
569-
570-
resources {
571-
from('src/main/asciidoc/querylanguage/') {
572-
include 'images/**'
573-
}
574-
from('src/main/style/asciidoctor') {
575-
include 'images/**'
576-
}
577-
from('src/main/style/asciidoctor') {
578-
include 'css/**'
579-
}
580-
from('src/main/style/asciidoctor') {
581-
include 'js/**'
582-
}
583-
}
584-
}
585-
586466
// User Guide ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
587467

588468
settingsDocumentation {
469+
anchorNameBase = "settings"
589470
sections {
590-
core {
591-
settingsClassName = "org.hibernate.cfg.AvailableSettings"
592-
projectPath = ":hibernate-core"
471+
compliance {
472+
explicitPosition = 1
473+
summary = "Jakarta Persistence Compliance Settings"
474+
description = "Settings which control various aspects of compliance with the Jakarta Persistence specification "
475+
settingsClassName "org.hibernate.cfg.JpaComplianceSettings"
476+
}
477+
persistence {
478+
explicitPosition = 2
479+
summary = "Persistence Unit Settings"
480+
description = "Settings related to the creation and configuration of a persistence-unit - SessionFactory and EntityManagerFactory"
481+
settingsClassName "org.hibernate.cfg.PersistenceSettings"
482+
}
483+
jdbc {
484+
explicitPosition = 3
485+
summary = "JDBC Settings"
486+
description = "Settings which control various aspects of how Hibernate interacts with JDBC"
487+
settingsClassName "org.hibernate.cfg.JdbcSettings"
488+
}
489+
c3p0 {
490+
explicitPosition = 4
491+
summary = "C3P0 Connection Pool Settings"
492+
description = "Settings related to integrating with the C3P0 Connection pool"
493+
settingsClassName "org.hibernate.cfg.C3p0Settings"
494+
}
495+
proxool {
496+
explicitPosition = 5
497+
summary = "Proxool Connection Pool Settings"
498+
description = "Settings related to integrating with the Proxool Connection pool"
499+
settingsClassName "org.hibernate.cfg.ProxoolSettings"
500+
}
501+
mapping {
502+
explicitPosition = 6
503+
summary = "Domain Mapping Settings"
504+
description = "Settings which control how domain mappings are handled"
505+
settingsClassName "org.hibernate.cfg.MappingSettings"
506+
}
507+
environment {
508+
summary = "Runtime Environment Settings"
509+
description = "Settings related to JNDI and ClassLoaders"
510+
settingsClassName "org.hibernate.cfg.EnvironmentSettings"
511+
}
512+
schema {
513+
summary = "Schema Tooling Settings"
514+
description = "Settings which control the creation, dropping, update and validation of database schemas"
515+
settingsClassName "org.hibernate.cfg.SchemaToolingSettings"
516+
}
517+
bytecode {
518+
summary = "Bytecode Manipulation Settings"
519+
description = "Settings which control Hibernate's BytecodeProvider used for bytecode manipulation"
520+
settingsClassName "org.hibernate.cfg.BytecodeSettings"
521+
}
522+
cache {
523+
summary = "Second-level Cache Settings"
524+
description = "Settings which control Hibernate's second-level caching"
525+
settingsClassName "org.hibernate.cfg.CacheSettings"
526+
settingsClassName "org.hibernate.cache.jcache.ConfigSettings"
527+
}
528+
query {
529+
summary = "Query Settings"
530+
description = "Settings which control various parts of Hibernate's Query handling"
531+
settingsClassName "org.hibernate.cfg.QuerySettings"
532+
}
533+
stats {
534+
summary = "Statistics Settings"
535+
description = "Settings which control the collection of statistics"
536+
settingsClassName "org.hibernate.cfg.StatisticsSettings"
537+
}
538+
validation {
539+
summary = "Jakarta Validation Integeration Settings"
540+
description = "Settings used in the integration of Jakarta Validation"
541+
settingsClassName "org.hibernate.cfg.ValidationSettings"
593542
}
594543
envers {
595-
settingsClassName = "org.hibernate.envers.configuration.EnversSettings"
596-
projectPath = ":hibernate-envers"
544+
summary = "Audit/History Settings"
545+
description = "Settings which control Hibernate's audit/history support (hibernate-envers)"
546+
settingsClassName "org.hibernate.envers.configuration.EnversSettings"
547+
}
548+
spatial {
549+
summary = "Hibernate Spatial Settings"
550+
description = "Settings which control Hibernate's support for spatial data (hibernate-spatial)"
551+
settingsClassName "org.hibernate.spatial.HibernateSpatialConfigurationSettings"
552+
settingsClassName "org.hibernate.spatial.integration.SpatialService"
597553
}
598-
jcache {
599-
settingsClassName = "org.hibernate.cache.jcache.ConfigSettings"
600-
projectPath = ":hibernate-jcache"
554+
misc {
555+
summary = "Miscellaneous Settings"
556+
description = "Miscellaneous Settings"
557+
settingsClassName "org.hibernate.cfg.AvailableSettings"
601558
}
602559
}
603560
}
604561

605562
def generateSettingsDocTask = tasks.named( "generateSettingsDoc" ) {
606563
dependsOn aggregateJavadocsTask
564+
565+
doFirst {
566+
def javadoc = aggregateJavadocsTask.get()
567+
def javaLanguageVersion = javadoc.javadocTool.present
568+
? javadoc.javadocTool.get().metadata.languageVersion
569+
: JavaLanguageVersion.of( JavaVersion.current().name )
570+
571+
if ( javaLanguageVersion.asInt() > 11 ) {
572+
println "Aggregated Javadocs was built using a JDK newer than version 11; generating the settings User Guide fragment will not succeed"
573+
}
574+
}
607575
}
608576

609577
def renderUserGuideHtmlTask = tasks.register( 'renderUserGuideHtml', AsciidoctorTask ) { task ->
610578
group = "Documentation"
611579
description = 'Renders the User Guides in HTML format using Asciidoctor.'
612580
inputs.property "hibernate-version", project.ormVersion
581+
inputs.file( generateSettingsDocTask.get().outputFile )
613582

614583
dependsOn generateSettingsDocTask
615584

‎gradle/java-module.gradle

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,12 @@ buildscript {
2121
import de.thetaphi.forbiddenapis.gradle.CheckForbiddenApis
2222
import org.apache.tools.ant.filters.ReplaceTokens
2323

24+
apply plugin: 'java-library'
25+
2426
apply from: rootProject.file( 'gradle/module.gradle' )
25-
apply from: rootProject.file( 'gradle/libraries.gradle' )
2627
apply from: rootProject.file( 'gradle/databases.gradle' )
28+
apply from: rootProject.file( 'gradle/javadoc.gradle' )
2729

28-
apply plugin: 'java-library'
2930
apply plugin: 'biz.aQute.bnd.builder'
3031
apply plugin: 'org.hibernate.orm.database-service'
3132
apply plugin: 'org.hibernate.orm.build.java-module'
@@ -58,6 +59,15 @@ if ( !project.description ) {
5859
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5960
// Configurations and Dependencies
6061

62+
configurations.configureEach {
63+
resolutionStrategy.eachDependency { details ->
64+
//Force the "byte buddy agent" version to match the Byte Buddy version
65+
// we use, as Mockito might pull in a mismatched version transitively
66+
if (details.requested.group == "net.bytebuddy" && details.requested.name == 'byte-buddy-agent') {
67+
details.useVersion libs.versions.byteBuddy.get()
68+
}
69+
}
70+
}
6171

6272
dependencies {
6373
implementation libs.logging
@@ -383,7 +393,12 @@ task sourcesJar(type: Jar) {
383393
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
384394
// Javadoc
385395

386-
apply from: rootProject.file( 'gradle/javadoc.gradle' )
396+
tasks.named( "javadoc", Javadoc ) {
397+
configure( options ) {
398+
windowTitle = "Hibernate Javadocs ($project.name)"
399+
docTitle = "Hibernate Javadocs ($project.name : $project.version)"
400+
}
401+
}
387402

388403
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
389404
// IDE

0 commit comments

Comments
 (0)