Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

HHH-9641 - Resume uploading Javadoc JARs to Maven 

HHH-12187 - Drop custom javadoc css

- delay package group calculations until execution (doFirst)
- exclude internal packages from javadoc
This commit is contained in:
Steve Ebersole 2017-12-26 11:27:58 -06:00
parent 6ccbd98bc3
commit 8c13488c5d
3 changed files with 114 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
build.gradle
View File

@ -359,27 +359,10 @@ subprojects { subProject ->
} }
javadoc { javadoc {
Set<String> apiPackages = new HashSet<>() exclude( "**/internal/*" )
Set<String> spiPackages = new HashSet<>() exclude( "**/generated-src/**" )
Set<String> internalPackages = new HashSet<>()
subProject.sourceSets.main.java.each { javaFile -> final int currentYear = new GregorianCalendar().get( Calendar.YEAR )
final String packageName = determinePackageName( subProject.sourceSets.main.java, javaFile );
if ( packageName.endsWith( ".internal" ) || packageName.contains( ".internal." ) ) {
internalPackages.add( packageName );
}
else if ( packageName.endsWith( ".spi" ) || packageName.contains( ".spi." ) ) {
spiPackages.add( packageName );
}
else if ( packageName.startsWith( "org.hibernate.testing" ) ) {
// do nothing as testing support is already handled...
}
else {
apiPackages.add( packageName );
}
}
final int copyrightYear = new GregorianCalendar().get( Calendar.YEAR )
configure( options ) { configure( options ) {
docletpath = configurations.asciidoclet.files.asType(List) docletpath = configurations.asciidoclet.files.asType(List)
@ -387,24 +370,55 @@ subprojects { subProject ->
windowTitle = "$subProject.name JavaDocs" windowTitle = "$subProject.name JavaDocs"
docTitle = "$subProject.name JavaDocs ($project.version)" docTitle = "$subProject.name JavaDocs ($project.version)"
bottom = "Copyright &copy; 2001-$copyrightYear <a href=\"http://redhat.com\">Red Hat, Inc.</a> All Rights Reserved." bottom = "Copyright &copy; 2001-$currentYear <a href=\"http://redhat.com\">Red Hat, Inc.</a> All Rights Reserved."
use = true use = true
encoding = 'UTF-8' encoding = 'UTF-8'
links += [ links += [
'https://docs.oracle.com/javase/8/docs/api/', 'http://docs.oracle.com/javase/8/docs/api/',
'https://docs.jboss.org/hibernate/beanvalidation/spec/2.0/api/', 'http://docs.jboss.org/hibernate/beanvalidation/spec/2.0/api/',
'http://docs.jboss.org/cdi/api/2.0/', 'http://docs.jboss.org/cdi/api/2.0/',
'https://docs.oracle.com/javaee/7/api/' 'http://docs.oracle.com/javaee/7/api/'
] ]
group( 'API', apiPackages.asList() )
group( 'SPI', spiPackages.asList() )
group( 'Internal', internalPackages.asList() )
group( 'Testing Support', ['org.hibernate.testing*'] )
if ( JavaVersion.current().isJava8Compatible() ) { if ( JavaVersion.current().isJava8Compatible() ) {
options.addStringOption( 'Xdoclint:none', '-quiet' ) options.addStringOption( 'Xdoclint:none', '-quiet' )
} }
doFirst {
// calculation of these groups is expensive - so push
// that process from init/configuration phase to execution
// phase.
//
// Note : this does not affect UP-TO-DATE checking because
// the groups are based on packages of the classes, and
// if the classes change that would already trigger
// re-execution of this task...
Set<String> apiPackages = new HashSet<>()
Set<String> spiPackages = new HashSet<>()
Set<String> testingPackages = new HashSet<String>()
subProject.sourceSets.main.java.each { javaFile ->
final String packageName = determinePackageName( subProject.sourceSets.main.java, javaFile );
if ( packageName.endsWith( ".internal" ) || packageName.contains( ".internal." ) ) {
// nothing to do - we exclude internal packages
}
else if ( packageName.endsWith( ".spi" ) || packageName.contains( ".spi." ) ) {
spiPackages.add( packageName )
}
else if ( packageName.startsWith( "org.hibernate.testing" ) ) {
testingPackages += packageName
}
else {
apiPackages.add( packageName )
}
}
options.group( 'API', apiPackages.asList() )
options.group( 'SPI', spiPackages.asList() )
options.group( 'Testing Support', testingPackages.asList() )
}
} }
} }

126
documentation/documentation.gradle
View File

@ -103,63 +103,27 @@ final File javadocDir = mkdir( new File( (File) project.buildDir, 'javadocs' ) )
* Builds the JavaDocs aggregated (unified) across all the sub-projects * Builds the JavaDocs aggregated (unified) across all the sub-projects
*/ */
task aggregateJavadocs(type: Javadoc) { task aggregateJavadocs(type: Javadoc) {
String[] projectsToSkip = ['release','documentation', 'hibernate-orm-modules']
description = 'Builds the aggregated (unified) JavaDocs across all sub-projects' description = 'Builds the aggregated (unified) JavaDocs across all sub-projects'
final int copyrightYear = new GregorianCalendar().get( Calendar.YEAR ); final int currentYear = new GregorianCalendar().get( Calendar.YEAR )
// exclude any generated sources (this is not working: http://forums.gradle.org/gradle/topics/excluding_generated_source_from_javadoc) // exclude any generated sources and internal packages
exclude "**/generated-src/**" exclude( '**/generated-src/**' )
exclude( '**/internal/**' )
// process each project, building up:
// 1) appropriate sources
// 2) classpath
// 3) the package list for groups
Set<String> apiPackages = new HashSet<String>()
Set<String> spiPackages = new HashSet<String>()
Set<String> internalPackages = new HashSet<String>()
parent.subprojects.each{ Project subProject->
// skip certain sub-projects
if ( ['release','documentation', 'hibernate-orm-modules'].contains( subProject.name ) ) {
return;
}
// we only care about the main SourceSet... // apply standard config
source subProject.sourceSets.main.java maxMemory = '512m'
destinationDir = javadocDir
if( classpath ) { configure( options ) {
classpath += subProject.sourceSets.main.output + subProject.sourceSets.main.compileClasspath overview = project.file( 'src/main/javadoc/overview.html' )
} windowTitle = 'Hibernate JavaDocs'
else { docTitle = "Hibernate JavaDoc ($project.version)"
classpath = subProject.sourceSets.main.output + subProject.sourceSets.main.compileClasspath bottom = "Copyright &copy; 2001-$currentYear <a href=\"http://redhat.com\">Red Hat, Inc.</a> All Rights Reserved."
} use = true
options.encoding = 'UTF-8'
subProject.sourceSets.main.java.each { javaFile ->
final String packageName = determinePackageName( subProject.sourceSets.main.java, javaFile );
if ( packageName.endsWith( ".internal" ) || packageName.contains( ".internal." ) ) {
internalPackages.add( packageName );
}
else if ( packageName.endsWith( ".spi" ) || packageName.contains( ".spi." ) ) {
spiPackages.add( packageName );
}
else if ( packageName.startsWith( "org.hibernate.testing" ) ) {
// do nothing as testing support is already handled...
}
else {
apiPackages.add( packageName );
}
}
}
// 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-$copyrightYear <a href=\"http://redhat.com\">Red Hat, Inc.</a> All Rights Reserved."
use = true
options.encoding = 'UTF-8'
links = [ links = [
'https://docs.oracle.com/javase/8/docs/api/', 'https://docs.oracle.com/javase/8/docs/api/',
@ -168,15 +132,63 @@ task aggregateJavadocs(type: Javadoc) {
'https://docs.oracle.com/javaee/7/api/' 'https://docs.oracle.com/javaee/7/api/'
] ]
group( 'API', apiPackages.asList() )
group( 'SPI', spiPackages.asList() )
group( 'Internal', internalPackages.asList() )
group ( 'Testing Support', ['org.hibernate.testing*'] )
if ( JavaVersion.current().isJava8Compatible() ) { if ( JavaVersion.current().isJava8Compatible() ) {
options.addStringOption( 'Xdoclint:none', '-quiet' ) options.addStringOption( 'Xdoclint:none', '-quiet' )
} }
}
// process each project, building up:
// 1) appropriate sources
// 2) classpath
parent.subprojects.each { Project subProject->
// skip certain sub-projects
if ( projectsToSkip.contains( subProject.name ) ) {
return
}
// we only care about the main SourceSet...
source subProject.sourceSets.main.java
// if( classpath ) {
classpath += subProject.sourceSets.main.output + subProject.sourceSets.main.compileClasspath
// }
// else {
// classpath = subProject.sourceSets.main.output + subProject.sourceSets.main.compileClasspath
// }
} }
doFirst {
Set<String> apiPackages = new HashSet<String>()
Set<String> spiPackages = new HashSet<String>()
Set<String> testingPackages = new HashSet<String>()
parent.subprojects.each { Project subProject ->
// skip certain sub-projects
if ( projectsToSkip.contains( subProject.name ) ) {
return
}
subProject.sourceSets.main.java.each { javaFile ->
final String packageName = determinePackageName( subProject.sourceSets.main.java, javaFile );
if ( packageName.endsWith( ".internal" ) || packageName.contains( ".internal." ) ) {
// do nothing - we exclude internal packages
}
else if ( packageName.endsWith( ".spi" ) || packageName.contains( ".spi." ) ) {
spiPackages.add( packageName )
}
else if ( packageName.startsWith( "org.hibernate.testing" ) ) {
testingPackages += packageName
}
else {
apiPackages.add( packageName )
}
}
}
options.group( 'API', apiPackages.asList() )
options.group( 'SPI', spiPackages.asList() )
options.group( 'Testing Support', testingPackages.asList() )
}
} }
asciidoctor { asciidoctor {

8
documentation/src/main/javadoc/overview.html
View File

@ -52,14 +52,10 @@ This documentation groups packages into the following 3 categories:<ul>
order to develop extensions to Hibernate, or to alter its behavior in some way. order to develop extensions to Hibernate, or to alter its behavior in some way.
</li> </li>
<li> <li>
<strong>Internal</strong> - classes which are intended only to be used by Hibernate. Use of these classes <strong>Testing Support</strong> - classes from the hibernate-testing artifact used in building Hibernate test cases.
outside of Hibernate specific use cases is not supported. Moreover, these contracts can change frequently
between releases whereas APIs and SPIs are more stable.
</li> </li>
</ul> </ul>
Additionally, we highlight a 4th category <strong>Testing Support</strong> which is a set of classes useful for building
Hibernate test cases.
<p></p>
<hr/> <hr/>
Complete Hibernate documentation may be found online at <a href="http://hibernate.org/orm/documentation">http://hibernate.org/orm/documentation/</a> Complete Hibernate documentation may be found online at <a href="http://hibernate.org/orm/documentation">http://hibernate.org/orm/documentation/</a>