From a1aa24119f4f5708844f3ce413ed4eebae13e1f7 Mon Sep 17 00:00:00 2001 From: David Smiley Date: Wed, 15 Jul 2026 18:24:09 -0400 Subject: [PATCH 1/2] Remove docs/ from the Solr binary distribution; fold links into README.txt The docs/ folder bundled in solr/packaging's distributions contained only a stub index.html redirecting to the real online documentation, plus an HTML rendering of CHANGELOG.md that already ships verbatim at the top level of the distribution. None of this was real documentation, so it is dropped from packaging and its two links (online docs, online Changes.html) are folded directly into README.txt's existing "Files included" section instead. The online docs link is version-pinned per release using the existing solrDocUrl property, substituted via a Gradle ReplaceTokens filter on README.txt, with a SNAPSHOT/custom-build fallback message for non-release builds. solr/packaging/build.gradle no longer depends on :solr:documentation's minimalSite configuration, and the corresponding docs entries were removed from smokeTestRelease.py's expected top-level directory lists for both the slim and full distributions. This also exposed that ./gradlew assemble was unconditionally rebuilding all of Solr's documentation (full javadocs, markdown-to-html, and the now-removed minimal stub site) via :solr:documentation's assemble task, even though that output is only needed by the release process (which invokes gradle documentation directly to publish to svn.apache.org/repos/infra/sites/solr/docs) or by the ref guide build (which resolves :solr:documentation's site/javadocs configurations explicitly). assemble no longer depends on the documentation task, and the root documentation task (used by the release wizard) now depends directly on :solr:documentation:documentation instead of routing through :solr:documentation:assemble. With packaging's last consumer gone, the entire minimalSite mechanism is deleted outright: the documentationMinimal, copyMiniDocumentationAssets, and copyChangesToHtmlForMiniSite tasks, the minimalSite configuration and artifact, the docrootMinimal property, the createMiniDocumentationIndex task, and its online-link.template.md template. Verified by building both distributions locally with SNAPSHOT and simulated release versions to confirm no docs/ directory ships and README.txt renders the correct URL or fallback text, by dry-running gw assemble/gw documentation/gw :solr:documentation:check to confirm the task graphs behave as expected, and by running :solr:documentation:documentation directly to confirm the full site still builds. --- dev-tools/scripts/smokeTestRelease.py | 4 +- gradle/documentation/documentation.gradle | 53 ++----------------- gradle/documentation/markdown.gradle | 9 ---- .../src/markdown/online-link.template.md | 21 -------- solr/packaging/README.txt | 11 +++- solr/packaging/build.gradle | 16 +++--- 6 files changed, 24 insertions(+), 90 deletions(-) delete mode 100644 solr/documentation/src/markdown/online-link.template.md diff --git a/dev-tools/scripts/smokeTestRelease.py b/dev-tools/scripts/smokeTestRelease.py index cd997b220b03..24a9e395e243 100755 --- a/dev-tools/scripts/smokeTestRelease.py +++ b/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)) diff --git a/gradle/documentation/documentation.gradle b/gradle/documentation/documentation.gradle index 8aa3f4a0bb01..700116ea13d1 100644 --- a/gradle/documentation/documentation.gradle +++ b/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,12 +77,11 @@ 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 { @@ -93,49 +89,10 @@ configure(project(':solr:documentation')) { 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 } } diff --git a/gradle/documentation/markdown.gradle b/gradle/documentation/markdown.gradle index 0506badfe8f3..eb9458bdb9cb 100644 --- a/gradle/documentation/markdown.gradle +++ b/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 diff --git a/solr/documentation/src/markdown/online-link.template.md b/solr/documentation/src/markdown/online-link.template.md deleted file mode 100644 index 64f208719c9f..000000000000 --- a/solr/documentation/src/markdown/online-link.template.md +++ /dev/null @@ -1,21 +0,0 @@ -
- - Solr - -
- TM -
-
- -# Apache Solr™ ${project.version} Documentation - -<% -if ("${project.version}" == "${project.baseVersion}") { // compare as strings because of lazy evaluation - println "Follow [this link to view online documentation](${project.solrDocUrl}) for Apache Solr ${project.version}." -} else { - println "No online documentation available for custom builds or `SNAPSHOT` versions." - println "Run `gradlew documentation` from `src.tgz` package to build docs locally." -} -%> - -Review the [changes](changes/Changes.html) in Apache Solr ${project.version}. diff --git a/solr/packaging/README.txt b/solr/packaging/README.txt index 8c5a69cbd5e4..7801ae00f491 100644 --- a/solr/packaging/README.txt +++ b/solr/packaging/README.txt @@ -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. diff --git a/solr/packaging/build.gradle b/solr/packaging/build.gradle index bebfdb4057e7..63c467388ef1 100644 --- a/solr/packaging/build.gradle +++ b/solr/packaging/build.gradle @@ -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,6 +34,9 @@ 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 { @@ -40,7 +44,6 @@ configurations { 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([ From c9abdb18af3e4f7c20043f17d73bcc39862c7317 Mon Sep 17 00:00:00 2001 From: David Smiley Date: Wed, 15 Jul 2026 18:36:47 -0400 Subject: [PATCH 2/2] changelog --- changelog/unreleased/PR#4641-remove_docs_distro.yml | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 changelog/unreleased/PR#4641-remove_docs_distro.yml diff --git a/changelog/unreleased/PR#4641-remove_docs_distro.yml b/changelog/unreleased/PR#4641-remove_docs_distro.yml new file mode 100644 index 000000000000..a95b65ec1756 --- /dev/null +++ b/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