You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by to...@apache.org on 2020/04/08 23:44:20 UTC
[lucene-solr] branch master updated: LUCENE-9278: Use -linkoffline
instead of relative paths to make links to other projects (#1388)
This is an automated email from the ASF dual-hosted git repository.
tomoko pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/lucene-solr.git
The following commit(s) were added to refs/heads/master by this push:
new 4f92cd4 LUCENE-9278: Use -linkoffline instead of relative paths to make links to other projects (#1388)
4f92cd4 is described below
commit 4f92cd414c4da6ac6163ff4101b0e07fb94fd067
Author: Tomoko Uchida <to...@gmail.com>
AuthorDate: Thu Apr 9 08:44:07 2020 +0900
LUCENE-9278: Use -linkoffline instead of relative paths to make links to other projects (#1388)
---
gradle/render-javadoc.gradle | 282 +++++++++++++++++-----------
gradle/validation/missing-docs-check.gradle | 4 +-
2 files changed, 179 insertions(+), 107 deletions(-)
diff --git a/gradle/render-javadoc.gradle b/gradle/render-javadoc.gradle
index 21d3dd7..bd22789 100644
--- a/gradle/render-javadoc.gradle
+++ b/gradle/render-javadoc.gradle
@@ -15,93 +15,139 @@
* 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 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()
+
+ def optionsFile = file("${getTemporaryDir()}/javadoc-options.txt")
+
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)
- }
+ def opts = []
+ opts += [ "-overview ${file("src/java/overview.html").toString()}" ]
+ opts += [ "-sourcepath ${srcDirs.join(' ')}" ]
+ opts += [ "-subpackages ${project.path.startsWith(':lucene') ? 'org.apache.lucene' : 'org.apache.solr'}"]
+ opts += [ "-d ${project.javadoc.destinationDir.toString()}" ]
+ opts += [ "-protected" ]
+ opts += [ "-encoding UTF-8" ]
+ opts += [ "-charset UTF-8" ]
+ opts += [ "-docencoding UTF-8" ]
+ opts += [ "-noindex" ]
+ opts += [ "-author" ]
+ opts += [ "-version" ]
+ if (linksource) {
+ opts += [ "-linksource" ]
+ }
+ opts += [ "-use" ]
+ opts += [ "-locale en_US" ]
+ opts += [ "-windowtitle '${title}'" ]
+ opts += [ "-doctitle '${title}'" ]
+ if (!sourceSets.main.compileClasspath.isEmpty()) {
+ opts += ["-classpath ${sourceSets.main.compileClasspath.asPath}" ]
+ }
+ opts += [ "-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")
+ opts += [ "-tag 'lucene.experimental:a:WARNING: This API is experimental and might change in incompatible ways in the next release.'" ]
+ opts += [ "-tag 'lucene.internal:a:NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.'" ]
+ opts += [ "-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())
- if (linkJUnit) {
- link(offline: "true", href: "https://junit.org/junit4/javadoc/4.12/", packageListLoc: project(":lucene").file("tools/javadoc/junit").toString())
- }
- // resolve inter-module links if 'linkHref' property is specified
- linkHref.collect { path ->
- link(href: path)
+ // resolve links to JavaSE and JUnit API
+ opts += [ "-linkoffline ${javaSEDocUrl} ${project(':lucene').file('tools/javadoc/java11/').toString()}" ]
+ if (linkJUnit) {
+ opts += [ "-linkoffline ${junitDocUrl} ${project(':lucene').file('tools/javadoc/junit').toURL()}" ]
+ }
+ // resolve inter-project links
+ linkLuceneProjects.collect { path ->
+ opts += [ "-linkoffline ${luceneDocUrl}/${pathToDocdir(path)} ${file(project(path).javadoc.destinationDir).toString()}" ]
+ }
+ linkSorlProjects.collect { path ->
+ opts += [ "-linkoffline ${solrDocUrl}/${pathToDocdir(path)} ${file(project(path).javadoc.destinationDir).toString()}" ]
+ }
+
+ opts += [ "--release 11" ]
+ opts += [ "-Xdoclint:all,-missing" ]
+
+ // Temporary file that holds all javadoc options for the current task.
+ optionsFile.write(opts.join("\n"), "UTF-8")
+
+ def outputFile = file("${getTemporaryDir()}/javadoc-output.txt")
+ def result
+ outputFile.withOutputStream { output ->
+ result = project.exec {
+ executable javadocCmd
+
+ standardOutput = output
+ errorOutput = output
+
+ args += [ "@${optionsFile}" ]
+
+ // -J flags can't be passed via options file... (an error "javadoc: error - invalid flag: -J-Xmx512m" occurs.)
+ args += [ "-J-Xmx512m" ]
+ // force locale to be "en_US" (fix for: https://bugs.openjdk.java.net/browse/JDK-8222793)
+ args += [ "-J-Duser.language=en -J-Duser.country=US" ]
+
+ ignoreExitValue true
}
+ }
- arg(line: "--release 11")
- arg(line: "-Xdoclint:all,-missing")
+ if (result.getExitValue() != 0) {
+ // Pipe the output to console. Intentionally skips any encoding conversion
+ // and pumps raw bytes.
+ System.out.write(outputFile.bytes)
- // force locale to be "en_US" (fix for: https://bugs.openjdk.java.net/browse/JDK-8222793)
- arg(line: "-J-Duser.language=en -J-Duser.country=US")
+ def cause
+ try {
+ result.rethrowFailure()
+ } catch (ex) {
+ cause = ex
+ }
+ throw new GradleException("Javadoc generation failed for ${project.path},\n Options file at: ${optionsFile}\n Command output at: ${outputFile}", cause)
}
// append some special table css, prettify css
- ant.concat(destfile: "${javadocDestDir}/stylesheet.css", append: "true", fixlastline: "true", encoding: "UTF-8") {
+ ant.concat(destfile: "${project.javadoc.destinationDir}/stylesheet.css", append: "true", fixlastline: "true", encoding: "UTF-8") {
filelist(dir: project(":lucene").file("tools/javadoc"), files: "table_padding.css")
filelist(dir: project(":lucene").file("tools/prettify"), files: "prettify.css")
}
// append prettify to scripts
- ant.concat(destfile: "${javadocDestDir}/script.js", append: "true", fixlastline: "true", encoding: "UTF-8") {
+ ant.concat(destfile: "${project.javadoc.destinationDir}/script.js", append: "true", fixlastline: "true", encoding: "UTF-8") {
filelist(dir: project(':lucene').file("tools/prettify"), files: "prettify.js inject-javadocs.js")
}
- ant.fixcrlf(srcdir: javadocDestDir, includes: "stylesheet.css script.js", eol: "lf", fixlast: "true", encoding: "UTF-8")
+ ant.fixcrlf(srcdir: project.javadoc.destinationDir, includes: "stylesheet.css script.js", eol: "lf", fixlast: "true", encoding: "UTF-8")
+
}
}
}
@@ -111,14 +157,16 @@ configure(subprojects.findAll { it.path.startsWith(':lucene') && it.path != ':lu
plugins.withType(JavaPlugin) {
renderJavadoc {
- dependsOn ':lucene:core:renderJavadoc'
- linkHref += [ "../core" ]
+ [':lucene:core'].collect { path ->
+ dependsOn "${path}:renderJavadoc"
+ linkLuceneProjects += [ path ]
+ }
doLast {
// fix for Java 11 Javadoc tool that cannot handle split packages between modules correctly (by removing all the packages which are part of lucene-core)
// problem description: [https://issues.apache.org/jira/browse/LUCENE-8738?focusedCommentId=16818106&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-16818106]
ant.local(name: "element-list-regex") // contains a regex for all package names which are in lucene-core's javadoc
- ant.loadfile(property: "element-list-regex", srcFile: "${project.javadocRoot}/core/element-list", encoding: "utf-8") {
+ ant.loadfile(property: "element-list-regex", srcFile: "${project(':lucene:core').javadoc.destinationDir}/element-list", encoding: "utf-8") {
filterchain {
tokenfilter(delimoutput: "|") {
replacestring(from: ".", to: "\\.")
@@ -127,7 +175,7 @@ configure(subprojects.findAll { it.path.startsWith(':lucene') && it.path != ':lu
}
ant.replaceregexp(
encoding: "UTF-8",
- file: "${project.javadocDestDir}/element-list",
+ file: "${project.javadoc.destinationDir}/element-list",
byline: "true",
match: "^(\${element-list-regex})\$",
replace: "")
@@ -136,16 +184,12 @@ configure(subprojects.findAll { it.path.startsWith(':lucene') && it.path != ':lu
}
}
-configure(subprojects.findAll { it.path.startsWith(':lucene:analysis') }) {
+configure(subprojects.findAll { it.path.startsWith(':lucene:analysis') && it.path != ':lucene:analysis:common'}) {
plugins.withType(JavaPlugin) {
- ext {
- javadocDestDir = "${javadocRoot}/analyzers-${project.name}"
- }
-
renderJavadoc {
- if (project.path != ':lucene:analysis:common') {
- dependsOn ':lucene:analysis:common:renderJavadoc'
- linkHref += [ "../analyzers-common" ]
+ [':lucene:analysis:common'].collect { path ->
+ dependsOn "${path}:renderJavadoc"
+ linkLuceneProjects += [ path ]
}
}
}
@@ -161,9 +205,8 @@ configure(project(':lucene:benchmark')) {
':lucene:facet',
':lucene:spatial-extras'].collect { path ->
dependsOn "${path}:renderJavadoc"
+ linkLuceneProjects += [ path ]
}
-
- linkHref += [ '../memory', '../highlighter', '../analyzers-common', '../queryparser', '../facet', '../spatial-extras' ]
}
}
}
@@ -173,9 +216,8 @@ configure(project(':lucene:classification')) {
renderJavadoc {
[':lucene:queries', ':lucene:analysis:common', ':lucene:grouping'].collect { path ->
dependsOn "${path}:renderJavadoc"
+ linkLuceneProjects += [ path ]
}
-
- linkHref += ['../queries', '../analyzers-common', '../grouping']
}
}
}
@@ -189,11 +231,11 @@ configure(project(':lucene:demo')) {
':lucene:facet',
':lucene:expressions'].collect { path ->
dependsOn "${path}:renderJavadoc"
+ linkLuceneProjects += [ path ]
}
- linkHref += ['../analyzers-common', '../queryparser', '../queries', '../facet', '../expressions']
// we link the example source in the javadocs, as it's ref'ed elsewhere
- linksource = "yes"
+ linksource = true
}
}
}
@@ -201,8 +243,10 @@ configure(project(':lucene:demo')) {
configure(project(':lucene:grouping')) {
plugins.withType(JavaPlugin) {
renderJavadoc {
- dependsOn ':lucene:queries:renderJavadoc'
- linkHref += [ '../queries' ]
+ [':lucene:queries'].collect { path ->
+ dependsOn "${path}:renderJavadoc"
+ linkLuceneProjects += [ path ]
+ }
}
}
}
@@ -210,8 +254,10 @@ configure(project(':lucene:grouping')) {
configure(project(':lucene:highlighter')) {
plugins.withType(JavaPlugin) {
renderJavadoc {
- dependsOn ':lucene:memory:renderJavadoc'
- linkHref += [ '../memory' ]
+ [':lucene:memory'].collect { path ->
+ dependsOn "${path}:renderJavadoc"
+ linkLuceneProjects += [ path ]
+ }
}
}
}
@@ -221,8 +267,8 @@ configure(project(':lucene:monitor')) {
renderJavadoc {
[':lucene:memory', ':lucene:analysis:common', ':lucene:queryparser'].collect { path ->
dependsOn "${path}:renderJavadoc"
+ linkLuceneProjects += [ path ]
}
- linkHref += [ '../memory', '../analyzers-common', '../queryparser' ]
}
}
}
@@ -232,8 +278,8 @@ configure(project(':lucene:queryparser')) {
renderJavadoc {
[':lucene:queries', ':lucene:sandbox'].collect { path ->
dependsOn "${path}:renderJavadoc"
+ linkLuceneProjects += [ path ]
}
- linkHref += [ '../queries', '../sandbox' ]
}
}
}
@@ -241,8 +287,10 @@ configure(project(':lucene:queryparser')) {
configure(project(':lucene:replicator')) {
plugins.withType(JavaPlugin) {
renderJavadoc {
- dependsOn ':lucene:facet:renderJavadoc'
- linkHref += [ '../facet' ]
+ [':lucene:facet'].collect { path ->
+ dependsOn "${path}:renderJavadoc"
+ linkLuceneProjects += [ path ]
+ }
}
}
}
@@ -250,8 +298,10 @@ configure(project(':lucene:replicator')) {
configure(project(':lucene:spatial-extras')) {
plugins.withType(JavaPlugin) {
renderJavadoc {
- dependsOn ':lucene:spatial3d:renderJavadoc'
- linkHref += [ '../spatial3d' ]
+ [':lucene:spatial3d'].collect { path ->
+ dependsOn "${path}:renderJavadoc"
+ linkLuceneProjects += [ path ]
+ }
}
}
}
@@ -259,32 +309,57 @@ configure(project(':lucene:spatial-extras')) {
configure(project(':lucene:suggest')) {
plugins.withType(JavaPlugin) {
renderJavadoc {
- dependsOn ':lucene:analysis:common:renderJavadoc'
- linkHref += [ '../analyzers-common' ]
+ [':lucene:analysis:common'].collect { path ->
+ dependsOn "${path}:renderJavadoc"
+ linkLuceneProjects += [ path ]
+ }
}
}
}
configure(project(':lucene:test-framework')) {
plugins.withType(JavaPlugin) {
+
renderJavadoc {
- dependsOn ':lucene:codecs:renderJavadoc'
+ [':lucene:codecs'].collect { path ->
+ dependsOn "${path}:renderJavadoc"
+ linkLuceneProjects += [ path ]
+ }
linkJUnit = true
- linkHref += [ '../codecs' ]
}
}
}
configure(subprojects.findAll { it.path.startsWith(':solr') }) {
plugins.withType(JavaPlugin) {
- ext {
- javadocDestDir = "${javadocRoot}/solr-${project.name}"
- }
-
def hasJavdocsTask = project.tasks.collect { it.name }.contains('renderJavadoc')
if (hasJavdocsTask) {
renderJavadoc {
- // TODO: generate links to lucene modules. i.e., port "solr-invoke-javadoc" Ant macro.
+ [':lucene:core',
+ ':lucene:analysis:common',
+ ':lucene:analysis:icu',
+ ':lucene:analysis:kuromoji',
+ ':lucene:analysis:nori',
+ ':lucene:analysis:morfologik',
+ ':lucene:analysis:phonetic',
+ ':lucene:analysis:smartcn',
+ ':lucene:analysis:stempel',
+ ':lucene:backward-codecs',
+ ':lucene:codecs',
+ ':lucene:expressions',
+ ':lucene:suggest',
+ ':lucene:grouping',
+ ':lucene:join',
+ ':lucene:queries',
+ ':lucene:queryparser',
+ ':lucene:highlighter',
+ ':lucene:memory',
+ ':lucene:misc',
+ ':lucene:classification',
+ ':lucene:spatial-extras'].collect { path ->
+ dependsOn "${path}:renderJavadoc"
+ linkLuceneProjects += [ path ]
+ }
}
}
}
@@ -294,8 +369,10 @@ configure(project(':solr:core')) {
plugins.withType(JavaPlugin) {
// specialized to ONLY depend on solrj
renderJavadoc {
- dependsOn ':solr:solrj:renderJavadoc'
- linkHref += [ '../solr-solrj' ]
+ [':solr:solrj'].collect { path ->
+ dependsOn "${path}:renderJavadoc"
+ linkSorlProjects += [ path ]
+ }
}
}
}
@@ -303,9 +380,10 @@ configure(project(':solr:core')) {
configure(subprojects.findAll { it.path.startsWith(':solr:contrib') }) {
plugins.withType(JavaPlugin) {
renderJavadoc {
- dependsOn ':solr:solrj:renderJavadoc'
- dependsOn ':solr:core:renderJavadoc'
- linkHref += [ '../solr-solrj', '../solr-core' ]
+ [':solr:solrj', ':solr:core'].collect { path ->
+ dependsOn "${path}:renderJavadoc"
+ linkSorlProjects += [ path ]
+ }
}
}
}
@@ -313,16 +391,10 @@ configure(subprojects.findAll { it.path.startsWith(':solr:contrib') }) {
configure(project(':solr:contrib:dataimporthandler-extras')) {
plugins.withType(JavaPlugin) {
renderJavadoc {
- dependsOn ':solr:contrib:dataimporthandler:renderJavadoc'
- linkHref += [ '../solr-dataimporthandler' ]
- }
- }
-}
-
-configure(project(':solr:contrib:extraction')) {
- plugins.withType(JavaPlugin) {
- ext {
- javadocDestDir = "${javadocRoot}/solr-cell"
+ [':solr:contrib:dataimporthandler'].collect { path ->
+ dependsOn "${path}:renderJavadoc"
+ linkSorlProjects += [ path ]
+ }
}
}
}
diff --git a/gradle/validation/missing-docs-check.gradle b/gradle/validation/missing-docs-check.gradle
index c759912..e465997 100644
--- a/gradle/validation/missing-docs-check.gradle
+++ b/gradle/validation/missing-docs-check.gradle
@@ -35,7 +35,7 @@ allprojects {
]
task checkMissingDocsDefault(type: CheckMissingDocsTask, dependsOn: 'renderJavadoc') {
- dirs += [ project.file(project.javadocDestDir) ]
+ dirs += [ project.javadoc.destinationDir ]
// TODO: add missing docs for all classes and bump this to level=class
if (project.path.startsWith(":solr")) {
@@ -71,7 +71,7 @@ configure(project(':lucene:core')) {
"org/apache/lucene/search/similarities",
"org/apache/lucene/index",
"org/apache/lucene/codecs"
- ].collect { path -> file("${project.javadocDestDir}/${path}") }
+ ].collect { path -> file("${project.javadoc.destinationDir}/${path}") }
checkMissingDocs {
dependsOn checkMissingDocsMethod