Copilot commented on code in PR #5049:
URL: https://github.com/apache/solr/pull/5049#discussion_r4324368316
##########
gradle/documentation/render-javadoc.gradle:
##########
@@ -483,3 +495,93 @@ class RenderJavadocTask extends DefaultTask {
encoding: "UTF-8")
}
}
+
+// The documentation site is rendered as two javadoc trees rather than one per
+// module: a unified tree holding every public package, and test-framework,
+// which shares a dozen packages with core and would otherwise put test
+// utilities on the public API pages.
+//
+// Both are hosted on projects that already have the Java plugin, the
+// missing-doclet configuration and minJavaVersion that RenderJavadocTask
needs.
+
+// Settings shared by both published trees. Each sits two directories below the
+// documentation root, hence the fixed docsRootPrefix.
+def siteJavadocDefaults = {RenderJavadocTask task ->
+ task.group = "documentation"
+ task.taskResources = resources
+ task.releaseVersion = task.project.minJavaVersion
+ task.enableSearch = true
+ task.docsRootPrefix = '../../'
+}
+
+configure(project(':solr:core')) {
+ // Deferred: the missing-doclet configuration this task type needs is itself
+ // created under plugins.withType(JavaPlugin), after the root script runs.
+ plugins.withType(JavaPlugin) {
+ task renderSiteJavadoc(type: RenderJavadocTask) {
+ description "Generates the unified Javadoc API documentation for the
site."
+ siteJavadocDefaults(delegate)
+
+ outputDir = project.docroot.toPath().resolve(UNIFIED_DOC_PATH).toFile()
+ sitewideSearch = true
+
+ // One run means one doclet configuration, so every split package that
any
+ // module used to excuse individually has to be excused here. Removing
+ // these is SOLR-15604.
+ javadocMissingIgnore = [
+ "org.apache.solr.schema",
+ "org.apache.solr.update.processor",
+ "org.apache.solr.common",
+ "org.apache.solr.common.cloud",
+ "org.apache.solr.client.solrj.cloud",
+ "org.apache.solr.client.solrj.embedded",
+ "org.apache.solr.client.solrj.impl"
+ ]
+ }
+ }
+}
+
+configure(project(':solr:test-framework')) {
+ plugins.withType(JavaPlugin) {
+ task renderSiteJavadoc(type: RenderJavadocTask) {
+ description "Generates the test-framework Javadoc API documentation for
the site."
+ siteJavadocDefaults(delegate)
+
+ dependsOn sourceSets.main.compileClasspath
Review Comment:
This site task reads `unifiedJavadocDir/element-list` while building the
test-framework tree, but the documentation task only depends on the unified and
test-framework render tasks independently. They can run in parallel, leaving
`element-list` absent when this task reaches `readLines()`; add an explicit
dependency on the core `renderSiteJavadoc` task.
##########
gradle/documentation/render-javadoc.gradle:
##########
@@ -483,3 +495,93 @@ class RenderJavadocTask extends DefaultTask {
encoding: "UTF-8")
}
}
+
+// The documentation site is rendered as two javadoc trees rather than one per
+// module: a unified tree holding every public package, and test-framework,
+// which shares a dozen packages with core and would otherwise put test
+// utilities on the public API pages.
+//
+// Both are hosted on projects that already have the Java plugin, the
+// missing-doclet configuration and minJavaVersion that RenderJavadocTask
needs.
+
+// Settings shared by both published trees. Each sits two directories below the
+// documentation root, hence the fixed docsRootPrefix.
+def siteJavadocDefaults = {RenderJavadocTask task ->
+ task.group = "documentation"
+ task.taskResources = resources
+ task.releaseVersion = task.project.minJavaVersion
+ task.enableSearch = true
+ task.docsRootPrefix = '../../'
+}
+
+configure(project(':solr:core')) {
+ // Deferred: the missing-doclet configuration this task type needs is itself
+ // created under plugins.withType(JavaPlugin), after the root script runs.
+ plugins.withType(JavaPlugin) {
+ task renderSiteJavadoc(type: RenderJavadocTask) {
+ description "Generates the unified Javadoc API documentation for the
site."
+ siteJavadocDefaults(delegate)
+
+ outputDir = project.docroot.toPath().resolve(UNIFIED_DOC_PATH).toFile()
+ sitewideSearch = true
+
+ // One run means one doclet configuration, so every split package that
any
+ // module used to excuse individually has to be excused here. Removing
+ // these is SOLR-15604.
+ javadocMissingIgnore = [
+ "org.apache.solr.schema",
+ "org.apache.solr.update.processor",
+ "org.apache.solr.common",
+ "org.apache.solr.common.cloud",
+ "org.apache.solr.client.solrj.cloud",
+ "org.apache.solr.client.solrj.embedded",
+ "org.apache.solr.client.solrj.impl"
+ ]
+ }
+ }
+}
+
+configure(project(':solr:test-framework')) {
+ plugins.withType(JavaPlugin) {
+ task renderSiteJavadoc(type: RenderJavadocTask) {
+ description "Generates the test-framework Javadoc API documentation for
the site."
+ siteJavadocDefaults(delegate)
+
+ dependsOn sourceSets.main.compileClasspath
+ classpath = sourceSets.main.compileClasspath
+ srcDirSet = sourceSets.main.java
+ relativeProjectLinks = true
+ outputDir =
project.docroot.toPath().resolve(TEST_FRAMEWORK_DOC_PATH).toFile()
+ unifiedJavadocDir =
project.docroot.toPath().resolve(UNIFIED_DOC_PATH).toFile()
+ }
+ }
+}
+
+// The unified tree's sources are every module's but test-framework's, which
can
+// only be collected once the subprojects have been evaluated.
+gradle.projectsEvaluated {
+ def host = project(':solr:core')
+ def modules = project(':solr').subprojects.findAll {
+ it.plugins.hasPlugin(JavaPlugin) &&
+ it.tasks.findByName('renderJavadoc')?.enabled &&
+ it.path != ':solr:test-framework'
+ }
+
+ def sources = host.objects.sourceDirectorySet('unifiedJavadoc', 'All Solr
module sources')
+ modules.each {mod -> mod.sourceSets.main.java.srcDirs.each
{sources.srcDir(it)}}
+
+ host.tasks.renderSiteJavadoc.configure {
+ srcDirSet = sources
+ classpath = host.files(modules.collect
{it.sourceSets.main.compileClasspath})
+ dependsOn modules.collect {it.tasks.named('compileJava')}
+ title = "Solr ${host.version} API"
+ }
+
+ // The per-module renderJavadoc output is what the Maven javadoc jars
package;
+ // point its external links at the unified tree.
+ project(':solr').subprojects.each {prj ->
+ prj.tasks.matching {it.name == 'renderJavadoc'}.configureEach {
+ unifiedJavadocDir = host.tasks.renderSiteJavadoc.outputDir
+ }
Review Comment:
This assigns the unified output to every per-module `renderJavadoc`, so
those tasks now add a `-linkoffline` entry pointing at
`build/site/javadocs/api` and fail at the validation in `render()` when that
directory has not already been generated. The normal `javadocJar` task depends
only on its module's `javadoc` task (`gradle/maven/defaults-maven.gradle:73`),
not on `renderSiteJavadoc`, so a standalone Maven/Javadoc build can now fail on
a missing `element-list`. Make these tasks depend on
`host.tasks.renderSiteJavadoc` (or otherwise make the link conditional) when
assigning this directory.
##########
solr/solr-ref-guide/antora.yml:
##########
@@ -40,7 +40,8 @@ asciidoc:
idprefix: ''
# 'patch-version' is the 'z' part of x.y.z semantic version
page-solr-javadocs: 'https://solr.apache.org/docs/11_0_0'
Review Comment:
This generated configuration has the same broken header target:
`ui-src/partials/header-content.hbs:29` appends `/index.html` to
`page-solr-javadocs`, so the Resources > Solr Javadocs link opens the docs
landing page rather than `javadocs/api/index.html`. Keep this page attribute on
the unified Javadoc tree.
##########
solr/solr-ref-guide/build.gradle:
##########
@@ -416,7 +416,8 @@ task buildLocalAntoraSite(type: NpxTask) {
// This attribute should not include ":link", the other 2 should
// This attribute should also not be relative, because it is used in
multiple path directories in the site
"--attribute",
"page-solr-javadocs=${project(':solr:documentation').docroot.toURI().toASCIIString()}",
Review Comment:
The local Antora build still supplies `page-solr-javadocs` as the
documentation root at line 418, while this new attribute only sets
`solr-javadocs`. Since the ref-guide header uses the page attribute for its
“Solr Javadocs” link, local builds still point that link at the docs landing
page; update the page attribute to the unified `javadocs/api` directory as well.
##########
solr/solr-ref-guide/modules/deployment-guide/pages/solrj.adoc:
##########
@@ -228,7 +228,7 @@ It is also suggested that Solr administrators commit
documents using Solr's auto
== Java Object Binding
While the `UpdateResponse` and `QueryResponse` interfaces that SolrJ provides
are useful, it is often more convenient to work with domain-specific objects
that can more easily be understood by your application.
-Thankfully, SolrJ supports this by implicitly converting documents to and from
any class that has been specially marked with
{solr-javadocs}/solrj/org/apache/solr/client/solrj//beans/Field.html[`Field`]
annotations.
+Thankfully, SolrJ supports this by implicitly converting documents to and from
any class that has been specially marked with
{solr-javadocs}/org/apache/solr/client/solrj//beans/Field.html[`Field`]
annotations.
Review Comment:
The migrated link still contains the old extra slash before `beans`, so it
resolves to `.../solrj//beans/Field.html` instead of the generated
`org/apache/solr/client/solrj/beans/Field.html` path. Remove the duplicate
slash.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
