LUCENE-9577: Move Lucene/Solr Documentation assembly to subproject (#1967)

gradle/documentation/changes-to-html.gradle

@@ -15,21 +15,32 @@
  * limitations under the License.
  */
 
-configure(subprojects.findAll { it.path == ':lucene' || it.path == ':solr' }) {
-  task changesToHtml(type: ChangesToHtmlTask)
+def resources = scriptResources(buildscript)
+
+configure(subprojects.findAll { it.path == ':lucene:documentation' || it.path == ':solr:documentation' }) {
+  task changesToHtml(type: ChangesToHtmlTask) {
+    siteDir = resources
+    script = file("${resources}/changes2html.pl")
+  }
 }
 
 // compile changes.txt into an html file
 class ChangesToHtmlTask extends DefaultTask {
 
-  @Input
-  File changesFile = project.file("CHANGES.txt")
+  @Internal
+  Project productProject = project.parent
 
-  @Input
-  File changesDoapFile = project.rootProject.file("dev-tools/doap/${project.name}.rdf")
+  @Internal
+  String productName = productProject.name
+
+  @InputFile
+  File changesFile = productProject.file('CHANGES.txt')
+
+  @InputFile
+  File changesDoapFile = project.rootProject.file("dev-tools/doap/${productName}.rdf")
 
   @InputDirectory
-  File siteDir = project.rootProject.file("lucene/site/changes")
+  File siteDir
 
   @OutputDirectory
   final DirectoryProperty targetDir = project.objects.directoryProperty()
@@ -39,11 +50,11 @@ class ChangesToHtmlTask extends DefaultTask {
   def luceneDocUrl = "${->project.luceneDocUrl}"
 
   @InputFile
-  def script = project.rootProject.file("${siteDir}/changes2html.pl")
+  def script
 
   def loadVersions(File outfile) {
     // load version properties from DOAP RDF
-    def prefix = "doap.${project.name}".toString()
+    def prefix = "doap.${productName}".toString()
     ant.xmlproperty(keeproot: false, file: changesDoapFile, collapseAttributes: false, prefix: "${prefix}")
     outfile.withWriter("UTF-8") { writer ->
       writer.println(ant.properties["${prefix}.Project.release.Version.revision"])
@@ -63,7 +74,7 @@ class ChangesToHtmlTask extends DefaultTask {
       args += [
         "-CSD",
         script,
-        "${project.name}",
+        "${productName}",
         versionsFile.toString(),
         luceneDocUrl.concat('/')   // slash required at end by perl script
       ]

gradle/documentation/documentation.gradle

@@ -23,7 +23,7 @@ configure(rootProject) {
     luceneDocUrl = project.propertyOrDefault('lucene.javadoc.url', {
       if (project.version != project.baseVersion) {
         // non-release build
-        project('lucene').file('build/documentation').toURI().toASCIIString()
+        new File(project('lucene:documentation').buildDir, 'site').toURI().toASCIIString().minus(~'/$')
       } else {
         // release build
         "https://lucene.apache.org/core/${urlVersion}"
@@ -33,7 +33,7 @@ configure(rootProject) {
     solrDocUrl = project.propertyOrDefault('solr.javadoc.url', {
       if (project.version != project.baseVersion) {
         // non-release build
-        project('solr').file('build/documentation').toURI().toASCIIString()
+        new File(project('solr:documentation').buildDir, 'site').toURI().toASCIIString().minus(~'/$')
       } else {
         // release build
         "https://lucene.apache.org/solr/${urlVersion}"
@@ -47,26 +47,27 @@ configure(rootProject) {
     group = 'documentation'
     description = 'Generate all documentation'
 
-    dependsOn ':lucene:documentation'
-    dependsOn ':solr:documentation'
+    dependsOn ':lucene:documentation:assemble'
+    dependsOn ':solr:documentation:assemble'
   }
 }
 
 // docroot will point to Lucene and Solr relative directory for each sub-project.
-configure(subprojects.findAll { it.path == ':lucene' || it.path == ':solr' }) {
-  ext {
-    docroot = file("${buildDir}/documentation")
-  }
+configure(subprojects.findAll { it.path == ':lucene:documentation' || it.path == ':solr:documentation' }) {
 
-  configurations {
-    docs
+  ext {
+    docroot = file("${buildDir}/site")
+    docrootMinimal = file("${buildDir}/minimalSite")
+
+    markdownSrc = file("src/markdown")
+    assets = file("src/assets")
   }
 
   task documentation() {
     group = 'documentation'
     description = "Generate ${project.name.capitalize()} documentation"
 
-    dependsOn subprojects.collect { prj ->
+    dependsOn project.parent.subprojects.collect { prj ->
       prj.tasks.matching { it.name == 'renderSiteJavadoc' }
     }
     dependsOn 'changesToHtml','copyDocumentationAssets',
@@ -75,55 +76,68 @@ configure(subprojects.findAll { it.path == ':lucene' || it.path == ':solr' }) {
 
   task copyDocumentationAssets(type: Copy) {
     includeEmptyDirs = false
-    from('site/html')      // lucene
-    from('site/assets')    // solr
+    from(project.assets)
     into project.docroot
   }
   
-  artifacts {
-    docs project.docroot, {
-      builtBy documentation
-    }
-  }
-}
-
-configure(project(':solr')) {
-  ext {
-    // required for the "simple" Solr docs shipped in tgz/zip files, only referring to online web pages:
-    docrootOnline = file("${buildDir}/docs-online")
+  assemble {
+    dependsOn documentation
   }
 
   configurations {
-    docsOnline
+    site
   }
   
-  documentation {
-    // for Solr we also have a page shipped with zip/tgz that just points to online web pages:
-    dependsOn 'documentationOnline'
+  artifacts {
+    site project.docroot, {
+      builtBy documentation
+    }
   }
 
-  task documentationOnline() {
+}
+
+configure(project(':solr:documentation')) {
+
+  task documentationMinimal() {
     group = 'documentation'
     description = "Generate stub Solr documentation pointing to web page (that's part of Solr TGZ)"
-    dependsOn 'copyOnlineDocumentationAssets','createOnlineDocumentationIndex','copyChangesToHtmlForOnline'
+    dependsOn 'copyMiniDocumentationAssets','createMiniDocumentationIndex','copyChangesToHtmlForMiniSite'
   }
 
-  task copyChangesToHtmlForOnline(type: Copy) {
+  task copyChangesToHtmlForMiniSite(type: Copy) {
     from project.docroot
-    into project.docrootOnline
+    into project.docrootMinimal
     include 'changes/**'
     dependsOn 'changesToHtml'
   }
 
-  task copyOnlineDocumentationAssets(type: Copy) {
+  task copyMiniDocumentationAssets(type: Copy) {
     includeEmptyDirs = false
-    from('site/assets')
-    into project.docrootOnline
+    from('src/assets')
+    into project.docrootMinimal
+  }
+
+  assemble {
+    dependsOn documentationMinimal
+  }
+
+  configurations {
+    minimalSite
   }
   
   artifacts {
-    docsOnline project.docrootOnline, {
-      builtBy documentationOnline
+    minimalSite project.docrootMinimal, {
+      builtBy documentationMinimal
     }
   }
+
+}
+
+configure(subprojects.findAll { it.path == ':lucene' || it.path == ':solr' }) {
+  
+  ext {
+    docroot = project('documentation').docroot
+    docrootMinimal = project('documentation').docrootMinimal
+  }
+
 }

gradle/documentation/markdown.gradle

@@ -40,7 +40,7 @@ buildscript {
   }
 }
 
-configure(subprojects.findAll { it.path == ':lucene' || it.path == ':solr' }) {
+configure(subprojects.findAll { it.path == ':lucene:documentation' || it.path == ':solr:documentation' }) {
   task markdownToHtml(type: Copy) {
     dependsOn copyDocumentationAssets
     
@@ -52,9 +52,9 @@ configure(subprojects.findAll { it.path == ':lucene' || it.path == ':solr' }) {
   }
 }
 
-configure(project(':lucene')) {
+configure(project(':lucene:documentation')) {
   markdownToHtml {
-    from('.') {
+    from(project.parent.projectDir) {
       include 'MIGRATE.md'
       include 'JRE_VERSION_MIGRATION.md'
       include 'SYSTEM_REQUIREMENTS.md'
@@ -62,10 +62,10 @@ configure(project(':lucene')) {
   }
   
   task createDocumentationIndex(type: MarkdownTemplateTask) {
-    dependsOn copyDocumentationAssets,markdownToHtml
+    dependsOn markdownToHtml
 
     outputFile = file("${project.docroot}/index.html")
-    templateFile = file('site/index.template.md')
+    templateFile = file("${project.markdownSrc}/index.template.md")
     
     def defaultCodecFile = project(':lucene:core').file('src/java/org/apache/lucene/codecs/Codec.java')
     inputs.file(defaultCodecFile)
@@ -87,19 +87,19 @@ configure(project(':lucene')) {
   }
 }
 
-configure(project(':solr')) {
+configure(project(':solr:documentation')) {
   markdownToHtml {
-    from('site') {
+    from(project.markdownSrc) {
       include '**/*.md'
       exclude '**/*.template.md'
     }
   }
   
   task createDocumentationIndex(type: MarkdownTemplateTask) {
-    dependsOn copyDocumentationAssets,markdownToHtml
+    dependsOn markdownToHtml
   
     outputFile = file("${project.docroot}/index.html")
-    templateFile = file('site/index.template.md')
+    templateFile = file("${project.markdownSrc}/index.template.md")
     
     // list all properties used by the template here to allow uptodate checks to be correct:
     inputs.property('version', project.version)
@@ -109,11 +109,9 @@ configure(project(':solr')) {
     withProjectList()
   }
   
-  task createOnlineDocumentationIndex(type: MarkdownTemplateTask) {
-    dependsOn copyOnlineDocumentationAssets
-  
-    outputFile = file("${project.docrootOnline}/index.html")
-    templateFile = file('site/online-link.template.md')
+  task createMiniDocumentationIndex(type: MarkdownTemplateTask) {
+    outputFile = file("${project.docrootMinimal}/index.html")
+    templateFile = file("${project.markdownSrc}/online-link.template.md")
 
     // list all properties used by the template here to allow uptodate checks to be correct:
     inputs.property('version', project.version)
@@ -161,6 +159,9 @@ class MarkdownFilter extends FilterReader {
 // produces Markdown, which is converted to HTML
 class MarkdownTemplateTask extends DefaultTask {
 
+  @Internal
+  Project productProject = project.parent
+
   @InputFile
   File templateFile
 
@@ -174,7 +175,7 @@ class MarkdownTemplateTask extends DefaultTask {
   /** adds a property "projectList" containing all subprojects with javadocs as markdown bullet list */
   void withProjectList() {
     binding.put('projectList', project.providers.provider{
-      def projects = project.subprojects.findAll{ it.tasks.findByName('renderSiteJavadoc')?.enabled }
+      def projects = productProject.subprojects.findAll{ it.tasks.findByName('renderSiteJavadoc')?.enabled }
         .sort(false, Comparator.comparing{ (it.name != 'core') as Boolean }
           .thenComparing(Comparator.comparing{ (it.name != 'solrj') as Boolean })
           .thenComparing(Comparator.comparing{ (it.name == 'test-framework') as Boolean })

lucene/documentation/build.gradle

@@ -0,0 +1,18 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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
+ *
+ *     http://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.
+ */
+
+description = 'Lucene HTML documentation'

lucene/packaging/build.gradle

@@ -28,8 +28,9 @@ description = 'Lucene distribution packaging'
 // By default everything is included, unless explicitly excluded.
 def includeInBinaries = project(":lucene").subprojects.findAll {subproject ->
     return !(subproject.path in [
-        // Exclude packaging, not relevant to binary distribution.
+        // Exclude packaging & documentation, not relevant to binary distribution.
         ":lucene:packaging",
+        ":lucene:documentation",
         // Exclude parent container project of analysis modules (no artifacts).
         ":lucene:analysis"
     ])
@@ -68,7 +69,7 @@ for (Project includedProject : includeInBinaries) {
 }
 
 dependencies {
-    docs project(path: ':lucene', configuration: 'docs')
+    docs project(path: ':lucene:documentation', configuration: 'site')
 }
 
 distributions {
@@ -143,10 +144,6 @@ configure(project(":lucene").subprojects) {
                 include "README.*"
             })
 
-            from(project.file('docs'), {
-                into 'docs'
-            })
-
             from(tasks.findByName("jar"))
 
             into packagingDir

settings.gradle

@@ -51,6 +51,7 @@ include "lucene:spatial-extras"
 include "lucene:spatial3d"
 include "lucene:suggest"
 include "lucene:test-framework"
+include "lucene:documentation"
 include "lucene:packaging"
 
 include "solr:solrj"
@@ -69,6 +70,7 @@ include "solr:test-framework"
 include "solr:solr-ref-guide"
 include "solr:example"
 
+include "solr:documentation"
 include "solr:packaging"
 include "solr:docker"
 include "solr:docker:package"

solr/documentation/build.gradle

@@ -0,0 +1,18 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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
+ *
+ *     http://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.
+ */
+
+description = 'Solr HTML documentation'

solr/documentation/src/markdown/index.template.md

@@ -1,6 +1,6 @@
 <div>
   <a href="http://lucene.apache.org/solr/">
-    <img src="images/solr.svg" style="width:210px; margin:22px 0px 7px 20px; border:none;" title="Apache Solr Logo" alt="Solr" />
+    <img src="solr.svg" style="width:210px; margin:22px 0px 7px 20px; border:none;" title="Apache Solr Logo" alt="Solr" />
   </a>
   <div style="z-index:100;position:absolute;top:25px;left:226px">
     <span style="font-size: x-small">TM</span>

solr/documentation/src/markdown/online-link.template.md

@@ -1,6 +1,6 @@
 <div>
   <a href="http://lucene.apache.org/solr/">
-    <img src="images/solr.svg" style="width:210px; margin:22px 0px 7px 20px; border:none;" title="Apache Solr Logo" alt="Solr" />
+    <img src="solr.svg" style="width:210px; margin:22px 0px 7px 20px; border:none;" title="Apache Solr Logo" alt="Solr" />
   </a>
   <div style="z-index:100;position:absolute;top:25px;left:226px">
     <span style="font-size: x-small">TM</span>

solr/packaging/build.gradle

@@ -38,7 +38,7 @@ configurations {
   contrib
   example
   server
-  docsOnline
+  docs
 }
 
 dependencies {
@@ -65,7 +65,7 @@ dependencies {
   server project(path: ":solr:server", configuration: "packaging")
 
   // Copy files from documentation output
-  docsOnline project(path: ':solr', configuration: 'docsOnline')
+  docs project(path: ':solr:documentation', configuration: 'minimalSite')
 }
 
 distributions {
@@ -121,7 +121,7 @@ distributions {
         into "server"
       })
 
-      from(configurations.docsOnline, {
+      from(configurations.docs, {
         into "docs"
       })
     }

solr/solr-ref-guide/build.gradle

@@ -103,6 +103,7 @@ sourceSets {
 
 ext {
     buildContentDir = file("${buildDir}/content")
+    htmlOutputDir = file("${buildDir}/html-site")
     mainPage = "index"
 
     // the "MAJOR.MINOR" version of solr this guide is about (guides aren't specific to BUGFIX releases)
@@ -114,8 +115,8 @@ ext {
     solrGuideVersionPath = "${solrDocsVersion}".replaceAll(/^(\d+)\.(\d+)$/, "\$1_\$2")
 
     if (project.hasProperty("local.javadocs")) {
-        htmlSolrJavadocs = "link:../../docs/"
-        htmlLuceneJavadocs = "link:../../../../lucene/build/docs/"
+        htmlSolrJavadocs = 'link:' + htmlOutputDir.toPath().relativize(project(':solr:documentation').docroot.toPath()).toString().replace(File.separator, '/')
+        htmlLuceneJavadocs = 'link:' + htmlOutputDir.toPath().relativize(project(':lucene:documentation').docroot.toPath()).toString().replace(File.separator, '/')
     } else {
         // when linking to javadocs of code releases, which always use paths like "MAJOR_MINOR_BUGFIX"
         // (even when 'BUGFIX' = 0), we link to the javadocs for the "MAJOR.MINOR.0" release
@@ -213,7 +214,7 @@ task buildSiteJekyll(type: com.github.jrubygradle.JRubyExec) {
     dependsOn buildNavDataFiles
 
     inputs.dir buildContentDir
-    outputs.dir file("${buildDir}/html-site")
+    outputs.dir htmlOutputDir
 
     script 'jekyll'
     scriptArgs 'build' //, '--verbose'
@@ -231,7 +232,7 @@ task buildSite(type: JavaExec) {
     workingDir = buildContentDir
 
     args([
-            file("${buildDir}/html-site"),
+            htmlOutputDir as String,
     ])
 
     if (project.hasProperty("local.javadocs")) {