packaging: Remove docs/ from the Solr binary distribution (apache#4641)

And add online links to README.txt

Author: dsmiley

changelog/unreleased/PR#4641-remove_docs_distro.yml

@@ -0,0 +1,8 @@
+title: >
+  Remove docs/ from the Solr binary distribution.  Add online links to such in README.txt
+type: other
+authors:
+  - name: David Smiley
+links:
+  - name: PR#4641
+    url: https://github.com/apache/solr/pull/4641

dev-tools/scripts/smokeTestRelease.py

@@ -679,9 +679,9 @@ def verifyBinaryUnpacked(java, artifact, unpackPath, version, gitRevision):
   is_in_list(in_root_folder, ['LICENSE.txt', 'NOTICE.txt', 'README.txt', 'CHANGELOG.md'])
 
   if isSlim:
-    is_in_list(in_root_folder, ['bin', 'docker', 'docs', 'example', 'licenses', 'server', 'lib'])
+    is_in_list(in_root_folder, ['bin', 'docker', 'example', 'licenses', 'server', 'lib'])
   else:
-    is_in_list(in_root_folder, ['bin', 'modules', 'cross-dc-manager', 'docker', 'docs', 'example', 'licenses', 'server', 'lib'])
+    is_in_list(in_root_folder, ['bin', 'modules', 'cross-dc-manager', 'docker', 'example', 'licenses', 'server', 'lib'])
 
   if len(in_root_folder) > 0:
     raise RuntimeError('solr: unexpected files/dirs in artifact %s: %s' % (artifact, in_root_folder))

gradle/documentation/documentation.gradle

@@ -47,17 +47,14 @@ configure(rootProject) {
     group = 'documentation'
     description = 'Generate all documentation'
 
-    dependsOn ':solr:documentation:assemble'
+    dependsOn ':solr:documentation:documentation'
   }
-
-  assemble.dependsOn documentation
 }
 
 // docroot will point to Lucene and Solr relative directory for each sub-project.
 configure(project(':solr:documentation')) {
   ext {
     docroot = file("${buildDir}/site")
-    docrootMinimal = file("${buildDir}/minimalSite")
 
     markdownSrc = file("src/markdown")
     assets = file("src/assets")
@@ -80,62 +77,22 @@ configure(project(':solr:documentation')) {
     into project.docroot
   }
 
-  assemble {
-    dependsOn documentation
-  }
-
   configurations {
-    site
+    // Not part of 'assemble': only built on demand (e.g. by the release process or the ref guide build).
+    site {
+      visible = false
+    }
   }
 
   artifacts {
     site project.docroot, {
       builtBy documentation
     }
   }
-
-  task documentationMinimal() {
-    group = 'documentation'
-    description = "Generate stub Solr documentation pointing to web page (that's part of Solr TGZ)"
-    dependsOn 'copyMiniDocumentationAssets',
-        'createMiniDocumentationIndex',
-        'copyChangesToHtmlForMiniSite'
-  }
-
-  task copyChangesToHtmlForMiniSite(type: Copy) {
-    dependsOn 'copyDocumentationAssets'
-    dependsOn 'markdownToHtml'
-
-    from project.docroot
-    into project.docrootMinimal
-    include 'changes/**'
-    dependsOn 'changesToHtml'
-  }
-
-  task copyMiniDocumentationAssets(type: Copy) {
-    includeEmptyDirs = false
-    from('src/assets')
-    into project.docrootMinimal
-  }
-
-  assemble {
-    dependsOn documentationMinimal
-  }
-
-  configurations {
-    minimalSite
-  }
-
-  artifacts {
-    minimalSite project.docrootMinimal, {
-      builtBy documentationMinimal
-    }
-  }
 }
 
 configure(project(":solr")) {
   ext {
     docroot = project('documentation').docroot
-    docrootMinimal = project('documentation').docrootMinimal
   }
 }

gradle/documentation/markdown.gradle

@@ -73,15 +73,6 @@ configure(project(':solr:documentation')) {
 
     withProjectList()
   }
-
-  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)
-    inputs.property('solrDocUrl', project.solrDocUrl).optional(true)
-  }
 }
 
 // filter that can be used with the "copy" task of Gradle that transforms Markdown files

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

@@ -81,8 +81,15 @@ docker/
   `docker/scripts` contains scripts that the Docker image uses to manage Solr.
   Refer to the README.md for instructions on how to build an image.
 
-docs/index.html
-  A link to the online version of Apache Solr Javadoc API documentation and Tutorial
+CHANGELOG.md
+  The list of changes in this release.
+
+Online Documentation
+  The online version of Apache Solr Javadoc API documentation and Tutorial:
+  @SOLR_DOC_URL@
+
+  Changes in this release are also published there, at:
+  @SOLR_CHANGES_URL@
 
 licenses/
   Licenses, notice files and signatures for Solr dependencies.

solr/packaging/README.txt

@@ -15,6 +15,7 @@
  * limitations under the License.
  */
 
+import org.apache.tools.ant.filters.ReplaceTokens
 import org.apache.tools.ant.util.TeeOutputStream
 
 // This project puts together a "distribution", assembling dependencies from
@@ -33,14 +34,16 @@ ext {
   devDir = file("$buildDir/dev")
   slimDevDir = file("$buildDir/dev-slim")
   batsLibsDir = file("$buildDir/bats-libs")
+  onlineDocUnavailable = "Not available for custom/SNAPSHOT builds -- run './gradlew documentation' from the source distribution to build docs locally."
+  onlineDocUrl = (project.solrDocUrl ? "${project.solrDocUrl}/" : onlineDocUnavailable).toString()
+  onlineChangesUrl = (project.solrDocUrl ? "${project.solrDocUrl}/changes/Changes.html" : onlineDocUnavailable).toString()
 }
 
 configurations {
   modules
   example
   crossDcManager
   server
-  docs
   docker
   solrFullTgz
   solrSlimTgz
@@ -58,9 +61,6 @@ dependencies {
   example project(path: ":solr:example", configuration: "packaging")
   server project(path: ":solr:server", configuration: "packaging")
 
-  // Copy files from documentation output
-  docs project(path: ':solr:documentation', configuration: 'minimalSite')
-
   docker project(path: ':solr:docker', configuration: 'packaging')
 
   solrFullTgzSignature files("$buildDir/distributions/solr-${version}.tgz.asc") {
@@ -92,6 +92,10 @@ distributions {
 
       from(projectDir, {
         include "README.txt"
+        filter(ReplaceTokens, tokens: [
+            SOLR_DOC_URL: onlineDocUrl,
+            SOLR_CHANGES_URL: onlineChangesUrl,
+        ])
       })
 
       from('static/lib', {
@@ -106,10 +110,6 @@ distributions {
         into "server"
       })
 
-      from(configurations.docs, {
-        into "docs"
-      })
-
       from(configurations.docker, {
         into "docker"
         filesMatching([