Publish docs to spring.io

.github/workflows/publish.yml

@@ -6,6 +6,10 @@ on:
       - 1.1.x
       - 1.0.x
 permissions: read-all
+env:
+    # reactor-netty/build will be uploaded to this artifact in the current workflow run
+    REACTOR_NETTY_BUILD_ARTIFACT: reactor-netty-build
+
 jobs:
   # General job notes: we DON'T want to cancel any previous runs, especially in the case of a "back to snapshots" build right after a release push
   # We specify the ubuntu version to minimize the chances we have to deal with a migration during a release
@@ -94,6 +98,15 @@ jobs:
           ORG_GRADLE_PROJECT_artifactory_publish_password: ${{secrets.ARTIFACTORY_PASSWORD}}
         run: |
           ./gradlew assemble artifactoryPublish -Partifactory_publish_contextUrl=https://repo.spring.io -Partifactory_publish_repoKey=libs-snapshot-local
+      - name: upload reactor-netty/build to current workflow run
+        uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 # v4
+        with:
+            name: ${{ env.REACTOR_NETTY_BUILD_ARTIFACT }}
+            retention-days: 3
+            if-no-files-found: error
+            path: |
+              reactor-netty/build/docs/javadoc
+              reactor-netty/build/asciidoc
 
   #sign the milestone artifacts and deploy them to Artifactory
   deployMilestone:
@@ -116,6 +129,15 @@ jobs:
           ORG_GRADLE_PROJECT_signingPassword: ${{secrets.SIGNING_PASSPHRASE}}
         run: |
           ./gradlew assemble sign artifactoryPublish -Partifactory_publish_contextUrl=https://repo.spring.io -Partifactory_publish_repoKey=libs-milestone-local
+      - name: upload reactor-netty/build to current workflow run
+        uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 # v4
+        with:
+            name: ${{ env.REACTOR_NETTY_BUILD_ARTIFACT }}
+            retention-days: 3
+            if-no-files-found: error
+            path: |
+                reactor-netty/build/docs/javadoc
+                reactor-netty/build/asciidoc
 
   #sign the release artifacts and deploy them to Artifactory
   deployRelease:
@@ -140,6 +162,15 @@ jobs:
           ORG_GRADLE_PROJECT_sonatypePassword: ${{secrets.SONATYPE_PASSWORD}}
         run: |
           ./gradlew assemble sign artifactoryPublish -Partifactory_publish_contextUrl=https://repo.spring.io  -Partifactory_publish_repoKey=libs-release-local publishMavenJavaPublicationToSonatypeRepository
+      - name: upload reactor-netty/build to current workflow run
+        uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 # v4
+        with:
+            name: ${{ env.REACTOR_NETTY_BUILD_ARTIFACT }}
+            retention-days: 3
+            if-no-files-found: error
+            path: |
+                reactor-netty/build/docs/javadoc
+                reactor-netty/build/asciidoc
 
   tagMilestone:
     name: Tag milestone
@@ -171,5 +202,48 @@ jobs:
           git tag -m "Release version ${{ needs.reactor-netty-core.outputs.fullVersion }}" v${{ needs.reactor-netty-core.outputs.fullVersion }} ${{ github.sha }}
           git push --tags
 
+  # deploy javadoc and reference doc into https://docs.spring.io/
+  deployDocs:
+    needs: [ deploySnapshot, deployRelease, deployMilestone ]
+    if: always() && (needs.deploySnapshot.result == 'success' || needs.deployRelease.result == 'success' || needs.deployMilestone.result == 'success')
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
+      - name: Setup java 11
+        uses: actions/setup-java@99b8673ff64fbf99d8d325f52d9a5bdedb8483e9 # v4
+        with:
+          distribution: 'temurin'
+          java-version: '11'
+      - name: download reactor-netty build
+        uses: actions/download-artifact@65a9edc5881444af0b9093a5e628f2fe47ea3b2e # v4
+        with:
+            name: ${{ env.REACTOR_NETTY_BUILD_ARTIFACT }}
+            path: reactor-netty/build
+      - name: deploy docs to docs.spring.io
+        env:
+          USER: ${{ secrets.DOCS_USERNAME }}
+          HOST: ${{ secrets.DOCS_HOST }}
+          KEY: ${{ secrets.DOCS_SSH_KEY }}
+          HOST_KEY: ${{ secrets.DOCS_SSH_HOST_KEY }}
+        run: |-
+          ./gradlew docs:deployDocs -PdeployDocsHost=$HOST -PdeployDocsSshUsername=$USER -PdeployDocsSshKey="$KEY" -PdeployDocsSshHostKey="$HOST_KEY"
+
+  cleanup:
+      needs: [ deployDocs ]
+      if: always() && needs.deployDocs.result == 'success'
+      runs-on: ubuntu-20.04
+      permissions:
+          actions: write
+      steps:
+          - name: delete reactor-netty build artifact
+            env:
+                GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+            run: |-
+                ARTIFACTS_URL="/repos/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}/artifacts"
+                ARTIFACT_ID=$(gh api -H 'Accept: application/vnd.github+json' -H 'X-GitHub-Api-Version: 2022-11-28' $ARTIFACTS_URL | jq -r '.artifacts[] | select(.name == "'$REACTOR_NETTY_BUILD_ARTIFACT'") | .id // ""')
+                if [ -n "$ARTIFACT_ID" ]; then
+                  gh api --method DELETE -H 'Accept: application/vnd.github+json' -H 'X-GitHub-Api-Version: 2022-11-28' /repos/${{github.repository}}/actions/artifacts/$ARTIFACT_ID}
+                fi
+
 # For Gradle configuration of signing, see https://docs.gradle.org/current/userguide/signing_plugin.html#sec:in-memory-keys
 # publishMavenJavaPublicationToSonatypeRepository only sends to a staging repository

build.gradle

@@ -125,6 +125,9 @@ ext {
 	errorproneCoreVersion = '2.10.0'
 	errorproneGuavaVersion = '30.0-jre'
 
+	// org.hidetake.ssh version
+	hidetakeSshVersion = '2.11.2'
+
 	javadocLinks = ["https://docs.oracle.com/javase/8/docs/api/",
 					// Use Reactive Streams 1.0.3 version for javadoc generation
 					// With Reactive Streams 1.0.4 version there is
@@ -166,9 +169,9 @@ spotless {
 	format 'gradle', {
 		target '**/*.gradle'
 		// find start of gradle files by looking for either `import`, `apply`
-		// or start of blocks like `javadoc{` or `configure(rootProject) {`...
+		// or start of blocks like `javadoc {` or `configure(rootProject) {`...
 		licenseHeaderFile('codequality/spotless/licenseSlashstarStyle.txt',
-				"^\\w+(\\(\\w+\\))?\\s?\\{\$|import|apply")
+				"^\\w+(\\(\\w+\\))?\\s?\\{?|import|apply")
 	}
 }
 
@@ -186,7 +189,7 @@ subprojects {
 
 	java {
 		toolchain {
-			languageVersion = JavaLanguageVersion.of(8)
+			languageVersion = JavaLanguageVersion.of(name == "docs" ? 11 : 8)
 		}
 	}
 

docs/build.gradle

@@ -0,0 +1,125 @@
+/*
+ * Copyright (c) 2024 VMware, Inc. or its affiliates, All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+plugins {
+	id 'org.hidetake.ssh' version "$hidetakeSshVersion"
+}
+
+description = "Reactor Netty spring.io docs"
+
+// Build a zip that contains both javadoc + reference doc
+task deployDocsZip(type: Zip) {
+	if (!file('../reactor-netty/build').exists()) {
+		logger.debug('Adding dependency on asciidoctor, asciidoctorPdf, javadoc')
+		// normally, it is expected the github workflow has already built ../reactor-netty/build/,
+		// if it's not the case, let's force rebuild of docs+javadocs
+		dependsOn(':reactor-netty:asciidoctor', ':reactor-netty:asciidoctorPdf', ':reactor-netty:javadoc')
+	}
+
+	archiveBaseName.set("reactor-netty")
+	archiveClassifier.set("apidocs")
+
+	from('../reactor-netty/build/asciidoc/pdf') {
+		include 'index.pdf'  // Include only the index.pdf file
+		into("reference/pdf/")
+		includeEmptyDirs = false
+		eachFile { fileCopyDetails ->
+			if (fileCopyDetails.name == 'index.pdf') {
+				fileCopyDetails.name = "reactor-netty-reference-guide-${rootProject.version}.pdf"
+			}
+		}
+	}
+	from('../reactor-netty/build/asciidoc/') {
+		includeEmptyDirs = false
+		exclude "**/index.pdf"
+		into("reference/html/")
+	}
+	from('../reactor-netty/build/docs/javadoc/') {
+		into "api"
+	}
+}
+
+remotes {
+	docs {
+		if (project.hasProperty('deployDocsSshHostKey') && project.hasProperty('deployDocsHost') && project.hasProperty('deployDocsSshUsername') && project.hasProperty('deployDocsSshKey')) {
+			// write content of known hosts into a temp file
+			def knownHostsFile = File.createTempFile("known_hosts_", ".txt")
+			knownHostsFile.text = project.findProperty('deployDocsSshHostKey')
+			knownHostsFile.deleteOnExit()
+
+			// configure ssh
+			role 'docs'
+			knownHosts = knownHostsFile
+			host = project.findProperty('deployDocsHost')
+			user = project.findProperty('deployDocsSshUsername')
+			identity = identity = project.findProperty('deployDocsSshKey')
+			retryCount = 5 // retry 5 times (default is 0)
+			retryWaitSec = 3 // wait 10 seconds between retries (default is 0)
+		}
+		else {
+			logger.debug("deployDocs ssh initialization skipped (no deployDocsSshHostKey/deployDocsHost/deployDocsSshUsername/deployDocsSshKey defined)")
+		}
+	}
+}
+
+// Deploy javadoc + reference to doc.spring.io:/opt/www/domains/spring.io/docs/htdocs/projectreactor/PROJECT_NAME/docs/PROJECT_VERSION/api/
+// Deploy reference (html) to doc.spring.io:/opt/www/domains/spring.io/docs/htdocs/projectreactor/PROJECT_NAME/docs/PROJECT_VERSION/reference/html
+// Deploy reference (pdf if any) to doc.spring.io:/opt/www/domains/spring.io/docs/htdocs/projectreactor/PROJECT_NAME/docs/PROJECT_VERSION/reference/pdf
+task deployDocs(dependsOn: [deployDocsZip]) {
+	doLast {
+		// Check if rootProject.name and rootProject.version are defined
+		if (!project.rootProject.hasProperty('name') || !project.rootProject.hasProperty('version')) {
+			throw new GradleException("deployDocs task failed: project.rootProject.name or project.rootProject.version undefined")
+		}
+
+		if (!project.hasProperty('deployDocsSshHostKey') || !project.hasProperty('deployDocsHost') ||
+				!project.hasProperty('deployDocsSshUsername') || !project.hasProperty('deployDocsSshKey')) {
+			throw new GradleException("deployDocs task failed: deployDocsSshHostKey/deployDocsHost/deployDocsSshUsername/deployDocsSshKey properties undefined")
+		}
+
+		ssh.run {
+			session(project.remotes.docs) {
+				def now = System.currentTimeMillis()
+				def name = project.rootProject.name
+				def version = project.rootProject.version
+				def tempPath = "/tmp/${name}-${now}-apidocs/".replaceAll(' ', '_')
+				execute "mkdir -p $tempPath"
+
+				// Download docs zip
+				project.tasks.deployDocsZip.outputs.each { o ->
+					put from: o.files, into: tempPath
+				}
+
+				// Unzip it in temp dir
+				execute "unzip $tempPath*.zip -d $tempPath"
+
+				// Move content to target extract dir
+				def extractPath = "/opt/www/domains/spring.io/docs/htdocs/projectreactor/${name}/docs/${version}/"
+
+				execute "rm -rf $extractPath"
+				execute "mkdir -p $extractPath"
+				execute "mv $tempPath* $extractPath"
+				execute "chmod -R g+w $extractPath"
+				execute "rm -rf $tempPath"
+				execute "rm -f $extractPath*.zip"
+
+				// update sym links with autoln command
+				execute "/opt/www/domains/spring.io/docs/autoln/bin/autoln create --scan-dir=/opt/www/domains/spring.io/docs/htdocs/projectreactor/${name}/docs/ --maxdepth=2"
+			}
+		}
+	}
+}
+
+

gradle/setup.gradle

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011-2023 VMware, Inc. or its affiliates, All Rights Reserved.
+ * Copyright (c) 2011-2024 VMware, Inc. or its affiliates, All Rights Reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,7 +15,7 @@
  */
 import org.gradle.util.VersionNumber
 
-if (project.name == 'reactor-netty-examples') {
+if (project.name == 'reactor-netty-examples' || project.name == 'docs') {
 	return
 }
 

settings.gradle

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011-2021 VMware, Inc. or its affiliates, All Rights Reserved.
+ * Copyright (c) 2011-2024 VMware, Inc. or its affiliates, All Rights Reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,4 +19,8 @@ include 'reactor-netty-http'
 include 'reactor-netty-http-brave'
 include 'reactor-netty-incubator-quic'
 include 'reactor-netty-examples'
-include 'reactor-netty'
+include 'reactor-netty'
+
+if (JavaVersion.current().isCompatibleWith(JavaVersion.VERSION_11)) {
+	include 'docs'
+}