mocobeta 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_r391504306
########## 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: > Ideally, I'd rather have the documentation follow gradle project path here. So ".../core/[ver]/analysis/icu/index.html", for example. I agree with that it makes things easy and i myself would love to throw away the convention come from Ant for simplicity. But changing folder structure on lucene.apahce.org would be a bit big change for devs, maybe it's required to gain an agreement with others...? ---------------------------------------------------------------- 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
