dweiss commented on a change in pull request #1388: LUCENE-9278: Use -linkoffline instead of relative paths to make links to other projects URL: https://github.com/apache/lucene-solr/pull/1388#discussion_r400788511
########## File path: gradle/render-javadoc.gradle ########## @@ -15,93 +15,105 @@ * limitations under the License. */ -// generate javadocs by using Ant javadoc task +// generate javadocs by calling javadoc tool +// see https://docs.oracle.com/en/java/javase/11/tools/javadoc.html + +// utility function to convert project path to document output dir +// e.g.: ':lucene:analysis:common' => 'analysis/common' +def pathToDocdir = { path -> path.split(':').drop(2).join('/') } allprojects { plugins.withType(JavaPlugin) { - ext { - javadocRoot = project.path.startsWith(':lucene') ? project(':lucene').file("build/docs") : project(':solr').file("build/docs") - javadocDestDir = "${javadocRoot}/${project.name}" - } - task renderJavadoc { - description "Generates Javadoc API documentation for the main source code. This invokes Ant Javadoc Task." + description "Generates Javadoc API documentation for the main source code. This directly invokes javadoc tool." group "documentation" ext { - linksource = "no" + linksource = false linkJUnit = false - linkHref = [] + linkLuceneProjects = [] + linkSorlProjects = [] } dependsOn sourceSets.main.compileClasspath inputs.files { sourceSets.main.java.asFileTree } - outputs.dir project.javadocRoot + outputs.dir project.javadoc.destinationDir def libName = project.path.startsWith(":lucene") ? "Lucene" : "Solr" def title = "${libName} ${project.version} ${project.name} API".toString() + // absolute urls for "-linkoffline" option + def javaSEDocUrl = "https://docs.oracle.com/en/java/javase/11/docs/api/"; + def junitDocUrl = "https://junit.org/junit4/javadoc/4.12/"; + def luceneDocUrl = "https://lucene.apache.org/core/${project.version.replace(".", "_")}".toString() + def solrDocUrl = "https://lucene.apache.org/solr/${project.version.replace(".", "_")}".toString() + + def javadocCmd = org.gradle.internal.jvm.Jvm.current().getJavadocExecutable() + doFirst { def srcDirs = sourceSets.main.java.srcDirs.findAll { dir -> dir.exists() } - ant.javadoc( - overview: file("src/java/overview.html"), - packagenames: "org.apache.lucene.*,org.apache.solr.*", - destDir: javadocDestDir, - access: "protected", - encoding: "UTF-8", - charset: "UTF-8", - docencoding: "UTF-8", - noindex: "true", - includenosourcepackages: "true", - author: "true", - version: "true", - linksource: linksource, - use: "true", - failonerror: "true", - locale: "en_US", - windowtitle: title, - doctitle: title, - maxmemory: "512m", - classpath: sourceSets.main.compileClasspath.asPath, - bottom: "<i>Copyright © 2000-${buildYear} Apache Software Foundation. All Rights Reserved.</i>" - ) { - srcDirs.collect { srcDir -> - packageset(dir: srcDir) + project.exec { + executable javadocCmd + + args += [ "-overview", file("src/java/overview.html").toString() ] + args += [ "-sourcepath", srcDirs.join(" ") ] + args += [ "-subpackages", project.path.startsWith(":lucene") ? "org.apache.lucene" : "org.apache.solr"] + args += [ "-d", project.javadoc.destinationDir.toString() ] + args += [ "-protected" ] + args += [ "-encoding", "UTF-8" ] + args += [ "-charset", "UTF-8" ] + args += [ "-docencoding", "UTF-8" ] + args += [ "-noindex" ] + args += [ "-author" ] + args += [ "-version" ] + if (linksource) { + args += [ "-linksource" ] } + args += [ "-use" ] + args += [ "-locale", "en_US" ] + args += [ "-windowtitle", title ] + args += [ "-doctitle", title ] + args += [ "-classpath", sourceSets.main.compileClasspath.asPath ] + args += [ "-bottom", "<i>Copyright © 2000-${buildYear} Apache Software Foundation. All Rights Reserved.</i>" ] - tag(name: "lucene.experimental", description: "WARNING: This API is experimental and might change in incompatible ways in the next release.") - tag(name: "lucene.internal", description: "NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.") - tag(name: "lucene.spi", description: "SPI Name (Note: This is case-insensitive. e.g., if the name is 'htmlStrip', 'htmlstrip' can be used when looking up the service):", scope: "types") + args += [ "-tag", "lucene.experimental:a:WARNING: This API is experimental and might change in incompatible ways in the next release." ] + args += [ "-tag", "lucene.internal:a:NOTE: This API is for internal purposes only and might change in incompatible ways in the next release." ] + args += [ "-tag", "lucene.spi:t:SPI Name (case-insensitive: if the name is 'htmlStrip', 'htmlstrip' can be used when looking up the service)." ] // resolve links to JavaSE and JUnit API - link(offline: "true", href: "https://docs.oracle.com/en/java/javase/11/docs/api/";, packageListLoc: project(":lucene").file("tools/javadoc/java11/").toString()) + args += [ "-linkoffline", javaSEDocUrl, project(":lucene").file("tools/javadoc/java11/").toURL() ] Review comment: Darn. I get execution error: > Task :lucene:core:renderJavadoc FAILED javadoc: error - Illegal package name: "<i>Copyright © 2000-2020 Apache Software Foundation. All Rights Reserved.</i>" 1 error FAILURE: Build failed with an exception. * Where: Script 'O:\repos\lucene-gradle-master\gradle\render-javadoc.gradle' line: 57 * What went wrong: Execution failed for task ':lucene:core:renderJavadoc'. > Process 'command 'C:\Tools\java\jdk\bin\javadoc.exe'' finished with non-zero exit value 2 * Try: Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights. * Get more help at https://help.gradle.org BUILD FAILED in 15s 2 actionable tasks: 1 executed, 1 up-to-date I think it's because something is escaped improperly. Let me look into this. ---------------------------------------------------------------- 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. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services --------------------------------------------------------------------- To unsubscribe, e-mail: issues-unsubscr...@lucene.apache.org For additional commands, e-mail: issues-h...@lucene.apache.org
