Skip to content

Commit

Permalink
PublishMigrationGuide task
Browse files Browse the repository at this point in the history
  • Loading branch information
sebersole committed Apr 1, 2023
1 parent efa7ec1 commit e93f44a
Show file tree
Hide file tree
Showing 8 changed files with 146 additions and 43 deletions.
73 changes: 39 additions & 34 deletions documentation/documentation.gradle
Expand Up @@ -42,7 +42,7 @@ dependencies {

if ( project.ormVersion.isSnapshot ) {
// only run the ci build tasks for SNAPSHOT versions
task ciBuild( dependsOn: [clean] )
tasks.register('ciBuild') { dependsOn clean }
tasks.release.enabled false
}
else {
Expand All @@ -53,12 +53,12 @@ else {
// grouping tasks - declaration, see below for task dependency definitions
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

task buildDocs {
tasks.register('buildDocs') {
group 'Documentation'
description 'Grouping task for performing all documentation building tasks'
}

task buildDocsForPublishing {
tasks.register('buildDocsForPublishing') {
group 'Documentation'
description 'Grouping task for building all documentation for publishing (release)'
}
Expand All @@ -76,12 +76,13 @@ asciidoctorj {

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

task renderTopicalGuides(type: AsciidoctorTask, group: 'Documentation') {task->
description = 'Renders the Topical Guides in HTML format using Asciidoctor.'
tasks.register('renderTopicalGuides', AsciidoctorTask) { task ->
description = 'Renders the Topical Guides in HTML format using Asciidoctor.'
tasks.buildDocs.dependsOn task
tasks.buildDocsForPublishing.dependsOn task
inputs.property "hibernate-version", project.ormVersion

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

resources {
Expand All @@ -94,20 +95,21 @@ task renderTopicalGuides(type: AsciidoctorTask, group: 'Documentation') {task->

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

task renderGettingStartedGuides(type: AsciidoctorTask, group: 'Documentation') {task->
description = 'Renders the Getting Started Guides (quick starts) in HTML format using Asciidoctor.'
tasks.register('renderGettingStartedGuides', AsciidoctorTask) { task ->
description = 'Renders the Getting Started Guides (quick starts) in HTML format using Asciidoctor.'
tasks.buildDocs.dependsOn task
tasks.buildDocsForPublishing.dependsOn task
inputs.property "hibernate-version", project.ormVersion

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


task buildTutorialZip(type: Zip) {task->
tasks.register('buildTutorialZip', Zip) { task ->
from 'src/main/asciidoc/quickstart/tutorials'
destinationDirectory = tasks.renderGettingStartedGuides.outputDir
archiveFileName = 'hibernate-tutorials.zip'
Expand All @@ -123,10 +125,11 @@ task buildTutorialZip(type: Zip) {task->

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

task renderUserGuide(type: AsciidoctorTask, group: 'Documentation') {task->
description = 'Renders the User Guides in HTML format using Asciidoctor.'
tasks.register('renderUserGuide', AsciidoctorTask) { task ->
description = 'Renders the User Guides in HTML format using Asciidoctor.'
tasks.buildDocs.dependsOn task
tasks.buildDocsForPublishing.dependsOn task
inputs.property "hibernate-version", project.ormVersion

dependsOn ':hibernate-core:collectConfigProperties'
dependsOn ':hibernate-envers:collectConfigProperties'
Expand All @@ -139,14 +142,14 @@ task renderUserGuide(type: AsciidoctorTask, group: 'Documentation') {task->
outputDir = "$buildDir/asciidoc/userguide/html_single"

attributes linkcss: true,
stylesheet: "css/hibernate.css",
docinfo: 'private',
jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/"
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/asciidoc/userguide/') {
include 'images/**'
}
from('src/main/style/asciidoctor') {
include 'images/**'
}
Expand All @@ -156,15 +159,17 @@ task renderUserGuide(type: AsciidoctorTask, group: 'Documentation') {task->
from('src/main/style/asciidoctor') {
include 'js/**'
}
}
}
}

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

task renderIntegrationGuide(type: AsciidoctorTask, group: 'Documentation') {task->
tasks.register( "renderIntegrationGuide", AsciidoctorTask.class, task-> {
group = "Documentation"
description = 'Renders the User Guides in HTML format using Asciidoctor.'
tasks.buildDocs.dependsOn task
tasks.buildDocsForPublishing.dependsOn task
inputs.property "hibernate-version", project.ormVersion

sourceDir = file( 'src/main/asciidoc/integrationguide' )
sources {
Expand All @@ -187,17 +192,18 @@ task renderIntegrationGuide(type: AsciidoctorTask, group: 'Documentation') {task
include 'css/**'
}
}
}
} )


// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Migration Guide

task renderMigrationGuide(type: AsciidoctorTask, group: 'Documentation') {task->
tasks.register( "renderMigrationGuide", AsciidoctorTask.class, task-> {
group = "Documentation"
description = 'Renders the Migration Guide in HTML format using Asciidoctor.'

tasks.buildDocs.dependsOn task
tasks.buildDocsForPublishing.dependsOn task
inputs.property "hibernate-version", project.ormVersion

sourceDir = rootProject.layout.projectDirectory
sources {
Expand All @@ -217,12 +223,12 @@ task renderMigrationGuide(type: AsciidoctorTask, group: 'Documentation') {task->
include 'css/**'
}
}
}
} )

// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// ORM Reports

task renderOrmReports { task ->
tasks.register('renderOrmReports') { task ->
group 'Documentation'
description 'Grouping task for rendering all ORM reports'

Expand All @@ -234,20 +240,19 @@ task renderOrmReports { task ->
tasks.buildDocsForPublishing.dependsOn task
}

task renderLoggingReport(type: AsciidoctorTask, group: 'Documentation') { task ->
tasks.register('renderLoggingReport', AsciidoctorTask) { task ->
group 'Documentation'
description = 'Renders the ORM logging report in HTML format using Asciidoctor.'

dependsOn tasks.generateLoggingReport

tasks.renderOrmReports.dependsOn task
inputs.property "version", project.ormVersion

sourceDir = layout.buildDirectory.dir( 'orm/reports' )
sourceDir = layout.buildDirectory.dir('orm/reports')
sources {
include 'logging.adoc'
}

outputDir = project.layout.buildDirectory.dir( 'asciidoc/logging' )
outputDir = project.layout.buildDirectory.dir('asciidoc/logging')

attributes linkcss: true,
stylesheet: "css/hibernate.css"
Expand Down
Expand Up @@ -47,6 +47,13 @@ public void apply(Project project) {
docPubDsl
);

final PublishMigrationGuide publishMigrationGuideTask = project.getTasks().create(
PublishMigrationGuide.NAME,
PublishMigrationGuide.class,
docPubDsl
);
publishMigrationGuideTask.getMigrationGuideDirectory().convention( project.getLayout().getBuildDirectory().dir( "asciidoc/migration-guide" ) );

// todo - incorporate HibernateVersion from `gradle/base-information.gradle`
final boolean isSnapshot = project.getVersion().toString().endsWith( "-SNAPSHOT" );
uploadTask.onlyIf( (task) -> !isSnapshot );
Expand Down
Expand Up @@ -31,6 +31,12 @@ public GenerateDescriptorTask(DocumentationPublishing config) {

jsonFile = config.getUpdatedJsonFile();
currentlyBuildingFamily = config.getReleaseFamilyIdentifier();

getInputs().property( "hibernate-version", currentlyBuildingFamily );
}

public ReleaseFamilyIdentifier getCurrentlyBuildingFamily() {
return currentlyBuildingFamily;
}

@OutputFile
Expand Down
Expand Up @@ -28,6 +28,8 @@ public PublishDescriptorTask(DocumentationPublishing config) {
setGroup( "Release" );
setDescription( "Publishes the documentation publication descriptor (JSON)" );

getInputs().property( "hibernate-version", getProject().getVersion() );

docServerUrl = config.getDocDescriptorServerUrl();
jsonFile = config.getUpdatedJsonFile();
}
Expand All @@ -49,11 +51,6 @@ public void uploadDescriptor() {
final String normalizedBase = base.endsWith( "/" ) ? base : base + "/";
final String url = normalizedBase + "_outdated-content/orm.json";

final String jsonPath = jsonFile.get().getAsFile().getAbsolutePath();

getProject().exec( (exec) -> {
exec.executable( "rsync" );
exec.args( "--port=2222", "-z", jsonPath, url );
} );
RsyncHelper.rsync( jsonFile.get(), url, getProject() );
}
}
@@ -0,0 +1,60 @@
package org.hibernate.orm.docs;

import javax.inject.Inject;

import org.gradle.api.DefaultTask;
import org.gradle.api.file.DirectoryProperty;
import org.gradle.api.provider.Provider;
import org.gradle.api.tasks.Input;
import org.gradle.api.tasks.InputDirectory;
import org.gradle.api.tasks.PathSensitive;
import org.gradle.api.tasks.PathSensitivity;
import org.gradle.api.tasks.TaskAction;

import org.hibernate.orm.ReleaseFamilyIdentifier;

/**
* @author Steve Ebersole
*/
public abstract class PublishMigrationGuide extends DefaultTask {
public static final String NAME = "publishMigrationGuide";

private final Provider<String> docServerUrl;

private final ReleaseFamilyIdentifier currentlyBuildingFamily;
private final DirectoryProperty migrationGuideDirectory;

@Inject
public PublishMigrationGuide(DocumentationPublishing config) {
setGroup( "Release" );
setDescription( "Publishes the migration-guide associated with the current branch. " +
"Intended for incremental publishing of the guide for corrections, etc. without doing a full release. " +
"Note that this is not needed when doing a release as the migration-guide is published as part of that workflow." );

getInputs().property( "hibernate-version", getProject().getVersion() );

docServerUrl = config.getDocServerUrl();
currentlyBuildingFamily = config.getReleaseFamilyIdentifier();
migrationGuideDirectory = getProject().getObjects().directoryProperty();
}

@InputDirectory
@PathSensitive(PathSensitivity.RELATIVE)
public DirectoryProperty getMigrationGuideDirectory() {
return migrationGuideDirectory;
}

@Input
public Provider<String> getDocServerUrl() {
return docServerUrl;
}

@TaskAction
public void uploadMigrationGuide() {
final String base = docServerUrl.get();
final String normalizedBase = base.endsWith( "/" ) ? base : base + "/";
final String url = normalizedBase + currentlyBuildingFamily.toExternalForm() + "/migration-guide/";

RsyncHelper.rsync( migrationGuideDirectory.get(), url, getProject() );
}
}
@@ -0,0 +1,22 @@
package org.hibernate.orm.docs;

import org.gradle.api.Project;
import org.gradle.api.file.FileSystemLocation;

/**
* Helper for performing rsync system commands, mainly used to centralize
* the command options
*
* @author Steve Ebersole
*/
public class RsyncHelper {
public static void rsync(
FileSystemLocation source,
String targetUrl,
Project project) {
project.exec( (exec) -> {
exec.executable( "rsync" );
exec.args( "--port=2222", "-avz", source.getAsFile().getAbsolutePath(), targetUrl );
} );
}
}
Expand Up @@ -10,6 +10,7 @@
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.Serializable;
import java.util.Properties;
import java.util.function.Consumer;

Expand All @@ -18,7 +19,7 @@
/**
* @author Steve Ebersole
*/
public class HibernateVersion {
public class HibernateVersion implements Serializable {
public static final String EXT_KEY = "ormVersion";
public static final String VERSION_KEY = "releaseVersion";
public static final String RELATIVE_FILE = "gradle/version.properties";
Expand Down
9 changes: 7 additions & 2 deletions release/release.gradle
Expand Up @@ -254,8 +254,13 @@ task stageMigrationGuide(type: Copy) {

dependsOn ':documentation:renderMigrationGuide'

from "${project( ':documentation' ).buildDir}/asciidoc/migration-guide"
into "${buildDir}/documentation/migration-guide"
from project(":documentation").layout.buildDirectory.dir("asciidoc/migration-guide")
into layout.buildDirectory.dir("documentation/migration-guide")
}

tasks.named( "publishMigrationGuide" ).configure {
dependsOn stageMigrationGuide
migrationGuideDirectory = project.layout.buildDirectory.dir("documentation/migration-guide")
}

task stageOrmReports {
Expand Down

0 comments on commit e93f44a

Please sign in to comment.