Create framework-docs module

This commit creates a new "framework-docs" module, which is dedicated to
documentation generation (reference and API docs).
This commit refactors the build configuration and moves the asciidoc
files to a separate location, but does not change the name nor the
nature of published artifacts.

Closes gh-29417

.gitignore

@@ -22,6 +22,7 @@ derby.log
 buildSrc/build
 /spring-*/build
 /framework-bom/build
+/framework-docs/build
 /integration-tests/build
 /src/asciidoc/build
 spring-test/test-output/

CONTRIBUTING.md

@@ -123,12 +123,12 @@ define the source file coding standards we use along with some IDEA editor setti
 
 ### Reference Docs
 
-The reference documentation is in the [src/docs/asciidoc](src/docs/asciidoc) directory, in
+The reference documentation is in the [framework-docs/src/docs/asciidoc](framework-docs/src/docs/asciidoc) directory, in
 [Asciidoctor](https://asciidoctor.org/) format. For trivial changes, you may be able to browse,
 edit source files, and submit directly from GitHub.
 
-When making changes locally, execute `./gradlew asciidoctor` and then browse the result under
-`build/docs/ref-docs/html5/index.html`.
+When making changes locally, execute `./gradlew :framework-docs:asciidoctor` and then browse the result under
+`framework-docs/build/docs/ref-docs/html5/index.html`.
 
 Asciidoctor also supports live editing. For more details see
 [AsciiDoc Tooling](https://docs.asciidoctor.org/asciidoctor/latest/tooling/).

README.md

@@ -1,4 +1,4 @@
-# <img src="src/docs/spring-framework.png" width="80" height="80"> Spring Framework [![Build Status](https://ci.spring.io/api/v1/teams/spring-framework/pipelines/spring-framework-5.3.x/jobs/build/badge)](https://ci.spring.io/teams/spring-framework/pipelines/spring-framework-5.3.x?groups=Build") [![Revved up by Gradle Enterprise](https://img.shields.io/badge/Revved%20up%20by-Gradle%20Enterprise-06A0CE?logo=Gradle&labelColor=02303A)](https://ge.spring.io/scans?search.rootProjectNames=spring)
+# <img src="framework-docs/src/docs/spring-framework.png" width="80" height="80"> Spring Framework [![Build Status](https://ci.spring.io/api/v1/teams/spring-framework/pipelines/spring-framework-5.3.x/jobs/build/badge)](https://ci.spring.io/teams/spring-framework/pipelines/spring-framework-5.3.x?groups=Build") [![Revved up by Gradle Enterprise](https://img.shields.io/badge/Revved%20up%20by-Gradle%20Enterprise-06A0CE?logo=Gradle&labelColor=02303A)](https://ge.spring.io/scans?search.rootProjectNames=spring)
 
 This is the home of the Spring Framework: the foundation for all [Spring projects](https://spring.io/projects). Collectively the Spring Framework and the family of Spring projects are often referred to simply as "Spring". 
 
@@ -14,7 +14,7 @@ For access to artifacts or a distribution zip, see the [Spring Framework Artifac
 
 ## Documentation
 
-The Spring Framework maintains reference documentation ([published](https://docs.spring.io/spring-framework/docs/current/spring-framework-reference/) and [source](src/docs/asciidoc)), GitHub [wiki pages](https://github.com/spring-projects/spring-framework/wiki), and an
+The Spring Framework maintains reference documentation ([published](https://docs.spring.io/spring-framework/docs/current/spring-framework-reference/) and [source](framework-docs/src/docs/asciidoc)), GitHub [wiki pages](https://github.com/spring-projects/spring-framework/wiki), and an
 [API reference](https://docs.spring.io/spring-framework/docs/current/javadoc-api/). There are also [guides and tutorials](https://spring.io/guides) across Spring projects.
 
 ## Micro-Benchmarks

build.gradle

@@ -1,11 +1,11 @@
 plugins {
 	id 'io.spring.nohttp' version '0.0.10'
 	id 'io.freefair.aspectj' version '6.5.0.3' apply false
-	id 'org.jetbrains.dokka' version '1.7.20' apply false
 	id 'org.jetbrains.kotlin.jvm' version '1.7.20' apply false
 	id 'org.jetbrains.kotlin.plugin.serialization' version '1.7.20' apply false
-	id 'org.asciidoctor.jvm.convert' version '3.3.2'
-	id 'org.asciidoctor.jvm.pdf' version '3.3.2'
+	id 'org.jetbrains.dokka' version '1.7.20'
+	id 'org.asciidoctor.jvm.convert' version '3.3.2' apply false
+	id 'org.asciidoctor.jvm.pdf' version '3.3.2'  apply false
 	id 'org.unbroken-dome.xjc' version '2.0.0' apply false
 	id 'com.github.ben-manes.versions' version '0.42.0'
 	id 'com.github.johnrengelman.shadow' version '7.1.2' apply false
@@ -60,8 +60,6 @@ configure([rootProject] + javaProjects) { project ->
 	}
 
 	pluginManager.withPlugin("kotlin") {
-		apply plugin: "org.jetbrains.dokka"
-		apply from: "${rootDir}/gradle/docs-dokka.gradle"
 
 		compileKotlin {
 			kotlinOptions {
@@ -170,8 +168,6 @@ configure(rootProject) {
 	apply plugin: "kotlin"
 	apply plugin: "io.spring.nohttp"
 	apply plugin: 'org.springframework.build.api-diff'
-	apply from: "${rootDir}/gradle/publications.gradle"
-	apply from: "${rootDir}/gradle/docs.gradle"
 
 	nohttp {
 		source.exclude "**/test-output/**"
@@ -192,13 +188,4 @@ configure(rootProject) {
 		maxHeapSize = "1g"
 	}
 
-	publishing {
-		publications {
-			mavenJava(MavenPublication) {
-				artifact docsZip
-				artifact schemaZip
-				artifact distZip
-			}
-		}
-	}
 }

gradle/docs.gradle → framework-docs/framework-docs.gradle

@@ -1,7 +1,23 @@
+description = "Spring Framework Docs"
+
+apply plugin: 'kotlin'
+apply plugin: 'org.asciidoctor.jvm.convert'
+apply plugin: 'org.asciidoctor.jvm.pdf'
+apply from: "${rootDir}/gradle/publications.gradle"
+
+
 configurations {
 	asciidoctorExtensions
 }
 
+jar {
+	enabled = false
+}
+
+javadoc {
+	enabled = false
+}
+
 dependencies {
 	asciidoctorExtensions "io.spring.asciidoctor.backends:spring-asciidoctor-backends:0.0.3"
 }
@@ -39,7 +55,7 @@ task api(type: Javadoc) {
 		author = true
 		header = rootProject.description
 		use = true
-		overview = "src/docs/api/overview.html"
+		overview = "framework-docs/src/docs/api/overview.html"
 		splitIndex = true
 		links(project.ext.javadocLinks)
 		addBooleanOption('Xdoclint:syntax', true) // only check syntax with doclint
@@ -55,14 +71,12 @@ task api(type: Javadoc) {
 /**
  * Produce KDoc for all Spring Framework modules in "build/docs/kdoc"
  */
-pluginManager.withPlugin("kotlin") {
-	tasks.dokkaHtmlMultiModule.configure {
-		dependsOn {
-			tasks.getByName("api")
-		}
-		moduleName.set("spring-framework")
-		outputDirectory.set(project.file("$buildDir/docs/kdoc"))
+rootProject.tasks.dokkaHtmlMultiModule.configure {
+	dependsOn {
+		tasks.getByName("api")
 	}
+	moduleName.set("spring-framework")
+	outputDirectory.set(project.file("$buildDir/docs/kdoc"))
 }
 
 asciidoctorj {
@@ -87,8 +101,8 @@ asciidoctorj {
 }
 
 /**
- * Generate the Spring Framework Reference documentation from "src/docs/asciidoc"
- * in "build/docs/ref-docs/html5".
+ * Generate the Spring Framework Reference documentation from
+ * "src/docs/asciidoc" in "build/docs/ref-docs/html5".
  */
 asciidoctor {
 	baseDirFollowsSourceDir()
@@ -128,7 +142,7 @@ asciidoctorPdf {
 /**
  * Zip all docs (API and reference) into a single archive
  */
-task docsZip(type: Zip, dependsOn: ['api', 'asciidoctor', 'asciidoctorPdf', 'dokkaHtmlMultiModule']) {
+task docsZip(type: Zip, dependsOn: ['api', 'asciidoctor', 'asciidoctorPdf', rootProject.tasks.dokkaHtmlMultiModule]) {
 	group = "Distribution"
 	description = "Builds -${archiveClassifier} archive containing api and reference " +
 			"for deployment at https://docs.spring.io/spring-framework/docs/."
@@ -147,7 +161,7 @@ task docsZip(type: Zip, dependsOn: ['api', 'asciidoctor', 'asciidoctorPdf', 'dok
 	from ("$asciidoctorPdf.outputDir") {
 		into "reference/pdf"
 	}
-	from (dokkaHtmlMultiModule.outputDirectory) {
+	from (rootProject.tasks.dokkaHtmlMultiModule.outputDirectory) {
 		into "kdoc-api"
 	}
 }
@@ -226,3 +240,14 @@ task distZip(type: Zip, dependsOn: [docsZip, schemaZip]) {
 }
 
 distZip.mustRunAfter moduleProjects.check
+
+
+publishing {
+	publications {
+		mavenJava(MavenPublication) {
+			artifact docsZip
+			artifact schemaZip
+			artifact distZip
+		}
+	}
+}

gradle/spring-module.gradle

@@ -13,6 +13,11 @@ dependencies {
 	jmh 'net.sf.jopt-simple:jopt-simple'
 }
 
+pluginManager.withPlugin("kotlin") {
+	apply plugin: "org.jetbrains.dokka"
+	apply from: "${rootDir}/gradle/docs-dokka.gradle"
+}
+
 jmh {
 	duplicateClassesStrategy = DuplicatesStrategy.EXCLUDE
 }
@@ -44,7 +49,7 @@ jar {
 	manifest.attributes["Created-By"] =
 			"${System.getProperty("java.version")} (${System.getProperty("java.specification.vendor")})"
 
-	from("${rootDir}/src/docs/dist") {
+	from("${rootDir}/framework-docs/src/docs/dist") {
 		include "license.txt"
 		include "notice.txt"
 		into "META-INF"

settings.gradle

@@ -35,6 +35,7 @@ include "spring-webflux"
 include "spring-webmvc"
 include "spring-websocket"
 include "framework-bom"
+include "framework-docs"
 include "framework-platform"
 include "integration-tests"