dweiss commented on a change in pull request #1304: LUCENE-9242: generate javadocs by calling Ant javadoc task URL: https://github.com/apache/lucene-solr/pull/1304#discussion_r391523979
########## File path: gradle/invoke-javadoc.gradle ########## @@ -0,0 +1,335 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +// invoke javadoc tool + +allprojects { + + ext { + javadocRoot = project.path.startsWith(':lucene') ? project(':lucene').file("build/docs") : project(':solr').file("build/docs") + javadocDestDir = "${javadocRoot}/${project.name}" + } + + plugins.withType(JavaPlugin) { + def libName = project.path.startsWith(":lucene") ? "Lucene" : "Solr" + def title = "${libName} ${project.version} ${project.name} API".toString() + def srcDirs = sourceSets.main.java.srcDirs.findAll { dir -> dir.exists() } + + task invokeJavadoc { + description "Generates Javadoc API documentation for the main source code. This invokes Ant Javadoc Task." + group "documentation" + + dependsOn sourceSets.main.compileClasspath + + inputs.property("linksource", "no") + inputs.property("linkJUnit", false) + inputs.property("linkHref", []) + + inputs.files sourceSets.main.java.asFileTree + outputs.dir project.javadocRoot + + doFirst { + srcDirs.each { srcDir -> + ant.javadoc( + overview: file("${srcDir}/overview.html"), + packagenames: "org.apache.lucene.*,org.apache.solr.*", + destDir: project.javadocDestDir, + access: "protected", + encoding: "UTF-8", + charset: "UTF-8", + docencoding: "UTF-8", + noindex: "true", + includenosourcepackages: "true", + author: "true", + version: "true", + linksource: inputs.properties.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>" + ) { + packageset(dir: srcDir) + + 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") + + // 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 (inputs.properties.get("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 + inputs.properties.get("linkHref").each { href -> + link(href: href) + } + + 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") + } + } + + // append some special table css, prettify css + ant.concat(destfile: "${javadocDestDir}/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") { + 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") + } + } + } +} + +configure(subprojects.findAll { it.path.startsWith(':lucene') && it.path != ':lucene:core' }) { + + plugins.withType(JavaPlugin) { + invokeJavadoc { + dependsOn ':lucene:core:invokeJavadoc' + + inputs.property('linkHref', inputs.properties.linkHref + [ '../core' ]) + + 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") { + filterchain { + tokenfilter(delimoutput: "|") { + replacestring(from: ".", to: "\\.") + } + } + } + ant.replaceregexp( + encoding: "UTF-8", + file: "${project.javadocDestDir}/element-list", + byline: "true", + match: "^(\${element-list-regex})\$", + replace: "") + + //println("dest dir = ${project.javadocDestDir}") + //println("linksource = ${inputs.properties.linksource}") + //println("link href = ${inputs.properties.linkHref}") + } + } + } +} + +configure(subprojects.findAll { it.path.startsWith(':lucene:analysis') }) { + ext { + javadocDestDir = "${javadocRoot}/analyzers-${project.name}" + } + + plugins.withType(JavaPlugin) { + invokeJavadoc { + if (project.path != ':lucene:analysis:common') { + dependsOn ':lucene:analysis:common:invokeJavadoc' + inputs.property('linkHref', inputs.properties.linkHref + [ '../analyzers-common' ]) + } + } + } +} + +configure(project(':lucene:benchmark')) { + plugins.withType(JavaPlugin) { + invokeJavadoc { + [':lucene:memory', + ':lucene:highlighter', + ':lucene:analysis:common', + ':lucene:queryparser', + ':lucene:facet', + ':lucene:spatial-extras'].collect { path -> + dependsOn "${path}:invokeJavadoc" + } + inputs.property('linkHref', inputs.properties.linkHref + [ '../memory', '../highlighter', '../analyzers-common', '../queryparser', '../facet', '../spatial-extras' ]) Review comment: I think this change should follow dropping ant build entirely from master. Then things become simpler to manage. These links are prefixed with version number anyway so I don't think there is harm in the docs structure changing for /9_0_0/.... ---------------------------------------------------------------- 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
