Apache
/
lucene
mirror of https://github.com/apache/lucene.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

LUCENE-9278: Use -linkoffline instead of relative paths to make links to other projects (#1388)

This commit is contained in:
Tomoko Uchida 2020-04-09 08:44:07 +09:00 committed by GitHub
parent dbb4be1ca9
commit 4f92cd414c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 180 additions and 108 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

284
gradle/render-javadoc.gradle
View File

@ -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 &copy; 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 &copy; 2000-${buildYear} Apache Software Foundation. All Rights Reserved.</i>'" ]
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
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
}
}
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")
if (result.getExitValue() != 0) {
// Pipe the output to console. Intentionally skips any encoding conversion
// and pumps raw bytes.
System.out.write(outputFile.bytes)
// 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())
def cause
try {
result.rethrowFailure()
} catch (ex) {
cause = ex
}
// resolve inter-module links if 'linkHref' property is specified
linkHref.collect { path ->
link(href: path)
}
arg(line: "--release 11")
arg(line: "-Xdoclint:all,-missing")
// 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")
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 ]
}
}
}
}

4
gradle/validation/missing-docs-check.gradle
View File

@ -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