HHH-16962 - General documentation improvements

https://hibernate.atlassian.net/browse/HHH-16962
This commit is contained in:
Steve Ebersole 2023-09-01 11:40:30 -05:00
parent c0fa25ade6
commit 32f635e752
5 changed files with 48 additions and 27 deletions

View File

@ -282,10 +282,23 @@ def renderTopicalGuidesTask = tasks.register( 'renderTopicalGuides', Asciidoctor
def gettingStartedGuideHtmlDir = layout.buildDirectory.dir( "asciidoc/quickstart/html_single" )
def buildTutorialZipTask = tasks.register( 'buildTutorialZip', Zip ) { task ->
from 'src/main/asciidoc/quickstart/tutorials'
destinationDirectory.set( gettingStartedGuideHtmlDir )
archiveFileName = 'hibernate-tutorials.zip'
expand(
version: project.version,
slf4j: "2.0.7",
junit: testLibs.versions.junit4.get(),
h2: dbLibs.versions.h2.get()
)
}
def renderGettingStartedGuideHtmlTask = tasks.register( 'renderGettingStartedGuideHtmlTask', AsciidoctorTask ) { task ->
group = "Documentation"
description = 'Renders the Getting Started Guides (quickstarts) in HTML format using Asciidoctor.'
inputs.property "hibernate-version", project.ormVersion
finalizedBy buildTutorialZipTask
sourceDir = file( 'src/main/asciidoc/quickstart/guides' )
sources 'index.adoc'
@ -325,18 +338,6 @@ def renderGettingStartedGuidePdfTask = tasks.register( 'renderGettingStartedGuid
attributes jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/"
}
def buildTutorialZipTask = tasks.register( 'buildTutorialZip', Zip ) { task ->
from 'src/main/asciidoc/quickstart/tutorials'
destinationDirectory.set( gettingStartedGuideHtmlDir )
archiveFileName = 'hibernate-tutorials.zip'
expand(
version: project.version,
slf4j: "2.0.7",
junit: testLibs.versions.junit4.get(),
h2: dbLibs.versions.h2.get()
)
}
def renderGettingStartedGuidesTask = tasks.register( 'renderGettingStartedGuides' ) { task ->
task.group = "Documentation"
task.description = 'Renders the Getting Started Guide in all formats, as well as the acccompanying tutorial zip.'
@ -658,15 +659,28 @@ def renderIntegrationGuidesTask = tasks.register( "renderIntegrationGuides" ) {
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Migration Guide
def renderMigrationGuideTask = tasks.register( "renderMigrationGuide", AsciidoctorTask ) { task ->
def migrationGuideSourceStagingDir = layout.buildDirectory.dir( "tmp/asciidoc/migration-guide" )
def copyMigrationGuideTask = tasks.register( "copyMigrationGuide", Copy ) {task ->
group = "Documentation"
description = 'Renders the Migration Guide in HTML format using Asciidoctor.'
description = "Copies migration-guide.adoc in preparation for rendering."
inputs.property "hibernate-version", project.ormVersion
sources {
include rootProject.layout.projectDirectory.file( 'migration-guide.adoc' ).asFile.canonicalPath
}
from rootProject.layout.projectDirectory.file( "migration-guide.adoc" )
into migrationGuideSourceStagingDir
}
def renderMigrationGuideTask = tasks.register( "renderMigrationGuide", AsciidoctorTask ) { task ->
group = "Documentation"
description = "Renders the Migration Guide in HTML format using Asciidoctor."
dependsOn copyMigrationGuideTask
inputs.property "hibernate-version", project.ormVersion
sourceDir = migrationGuideSourceStagingDir
outputDir = project.layout.buildDirectory.dir( 'asciidoc/migration-guide' )
attributes linkcss: true,
stylesheet: "css/hibernate.css"

View File

@ -60,7 +60,7 @@ public class DocumentationPublishingPlugin implements Plugin<Project> {
(task) -> {
task.getCurrentlyBuildingFamily().convention( docPubDsl.getReleaseFamilyIdentifier() );
task.getDocServerUrl().convention( docPubDsl.getDocServerUrl() );
task.getMigrationGuideDirectory().convention( project.getLayout().getBuildDirectory().dir( "asciidoc/migration-guide" ) );
task.getMigrationGuideDirectory().convention( project.getLayout().getBuildDirectory().dir( "documentation/migration-guide" ) );
}
);

View File

@ -54,6 +54,8 @@ public abstract class PublishMigrationGuide extends DefaultTask {
return docServerUrl;
}
@Input
public Property<ReleaseFamilyIdentifier> getCurrentlyBuildingFamily() {
return currentlyBuildingFamily;
}

View File

@ -32,7 +32,7 @@ public class DeprecationReportTask extends AbstractJandexAwareTask {
public DeprecationReportTask() {
setDescription( "Generates a report for things considered deprecated" );
reportFile = getProject().getObjects().fileProperty();
reportFile.convention( getProject().getLayout().getBuildDirectory().file( "orm/reports/deprecating.txt" ) );
reportFile.convention( getProject().getLayout().getBuildDirectory().file( "orm/reports/deprecated.txt" ) );
}
@Override

View File

@ -1,11 +1,14 @@
= Hibernate {{version-here}}
:family: 6.3
:version: 6.3.0.Final
= Hibernate {version}
Steve Ebersole
:awestruct-tags: ["Hibernate ORM", "Releases"]
:awestruct-layout: blog-post
:version: {{version-here}}
:docs-url: https://docs.jboss.org/hibernate/orm/{version}
:docs-url: https://docs.jboss.org/hibernate/orm/{family}
:javadocs-url: {docs-url}/javadocs
:migration-guide-url: {docs-url}/migration-guide/migration-guide.html
:intro-guide-url: {docs-url}/introduction/html_single/Hibernate_Introduction.html
:user-guide-url: {docs-url}/userguide/html_single/Hibernate_User_Guide.html
// Text ...
@ -15,15 +18,17 @@ Steve Ebersole
For additional details, see:
- the link:{user-guide-url}[User Guide]
- the link:{migration-guide-url}[Migration Guide]
- the https://hibernate.org/orm/releases/6.0/[release page]
- the link:{migration-guide-url}[Migration Guide]
- the link:{intro-guide-url}[Hibernate 6 Introduction]
- the link:{user-guide-url}[User Guide]
See also the following resources related to supported APIs:
- the link:{docs-url}/incubating/incubating.txt[incubating API report] - `@Incubating`
- the link:{docs-url}/deprecated/deprecated.txt[deprecated API report] - `@Deprecated` + `@Remove`
- the link:{docs-url}/internals/internal.txt[internal API report] - internal packages, `@Internal`
- the https://hibernate.org/community/compatibility-policy/[compatibility policy]
- the link:{docs-url}/incubating/incubating.txt[incubating API report] (`@Incubating`)
- the link:{docs-url}/deprecated/deprecated.txt[deprecated API report] (`@Deprecated` + `@Remove`)
- the link:{docs-url}/internals/internal.txt[internal API report] (internal packages, `@Internal`)
Visit the https://hibernate.org/community/[website] for details on getting in touch with us.