mocobeta commented on a change in pull request #1488:
URL: https://github.com/apache/lucene-solr/pull/1488#discussion_r420737101
##########
File path: gradle/render-javadoc.gradle
##########
@@ -430,3 +305,180 @@ configure(subprojects.findAll { it.path in
[':solr:solr-ref-guide', ':solr:serve
project.tasks.findByPath("renderJavadoc").enabled = false
}
}
+
+class RenderJavadocTask extends DefaultTask {
+ @InputFiles
+ @SkipWhenEmpty
+ SourceDirectorySet srcDirSet;
+
+ @OutputDirectory
+ File outputDir;
+
+ @InputFiles
+ @Classpath
+ FileCollection classpath;
+
+ @Input
+ boolean linksource = false;
+
+ @Input
+ boolean linkJUnit = false;
+
+ @Input
+ boolean relativeProjectLinks = true;
+
+ @Input
+ def linkProjects = [];
+
+ @Input
+ def luceneDocUrl = project.propertyOrDefault('lucene.javadoc.url',
"https://lucene.apache.org/core/${project.baseVersion.replace(".", "_")}")
+
+ @Input
+ def solrDocUrl = project.propertyOrDefault('solr.javadoc.url',
"https://lucene.apache.org/solr/${project.baseVersion.replace(".", "_")}")
+
+ @TaskAction
+ public void render() {
+ def thispc = project.path.split(':').drop(1);
+ // Converts absolute project path (e.g., ":lucene:analysis:common") to
+ // a link in the docs; relative to current, if needed for global
documentation
+ def convertPath2Link = { path ->
+ def pc = path.split(':').drop(1);
+ if (relativeProjectLinks) {
+ int toDrop = 0;
+ for (int i = 0; i < Math.min(pc.size(), thispc.size()); i++) {
+ if (pc[i] == thispc[i]) {
+ toDrop++;
+ } else {
+ break;
+ }
+ }
+ // only create relative path if there is actually anything removed
from beginning (this implies absolute link solr -> lucene):
+ if (toDrop > 0) {
+ return Collections.nCopies(thispc.size() - toDrop,
'..').plus(pc.drop(toDrop) as List).join('/').concat('/');
+ }
+ }
+ return "${(pc[0] == 'lucene') ? luceneDocUrl :
solrDocUrl}/${pc.drop(1).join('/')}/"
+ }
+
+ // escapes an option with single quotes or whitespace to be passed in the
options.txt file for
+ def escapeJavadocOption = { String s -> (s =~ /[ '"]/) ? ("'" +
s.replaceAll(/[\\'"]/, /\\$0/) + "'") : s }
+
+ def relativizeURL = { String from, String to ->
+ URI fromUri = URI.create(from).normalize();
+ URI toUri = URI.create(to).normalize();
+ if (fromUri.scheme != toUri.scheme || fromUri.authority !=
toUri.authority) {
+ return to;
+ }
+ // because URI#relativice can't handle relative paths, we use Path class
as workaround
+ Path fromPath = Paths.get("./${fromUri.path}");
+ Path toPath = Paths.get("./${toUri.path}");
+ return fromPath.relativize(toPath).toString().replace(File.separator,
'/')
+ }
+
+ def libName = project.path.startsWith(":lucene") ? "Lucene" : "Solr"
+ def title = "${libName} ${project.version} ${project.name} API"
+
+ // 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 javadocCmd =
org.gradle.internal.jvm.Jvm.current().getJavadocExecutable()
+
+ def srcDirs = srcDirSet.srcDirs.findAll { dir -> dir.exists() }
+ def optionsFile = project.file("${getTemporaryDir()}/javadoc-options.txt")
+
+ def opts = []
+ opts << [ '-overview', project.file("${srcDirs[0]}/overview.html") ]
+ opts << [ '-sourcepath', srcDirs.join(File.pathSeparator) ]
+ opts << [ '-subpackages', project.path.startsWith(':lucene') ?
'org.apache.lucene' : 'org.apache.solr' ]
+ opts << [ '-d', outputDir ]
+ 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 (!classpath.isEmpty()) {
+ opts << [ '-classpath', classpath.asPath ]
+ }
+ opts << [ '-bottom', "<i>Copyright © 2000-${project.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.project(':lucene').file('tools/javadoc/java11/') ]
+ if (linkJUnit) {
+ opts << [ '-linkoffline', junitDocUrl,
project.project(':lucene').file('tools/javadoc/junit/') ]
+ }
+ // resolve inter-project links
+ linkProjects.collect { path ->
+ def docdir = convertPath2Link(path)
+ logger.warn(docdir as String);
+ opts << [ '-linkoffline', docdir,
project.project(path).javadoc.destinationDir ]
Review comment:
To generate relative links, have you considered to use `-link` (as the
original ant task does so) option instead of `-linkoffline` ? The first version
of "renderJavadoc" had also used `-link` option with relative file paths before
we changed it to absolute urls. (I'm not sure if it makes sense here and have
no strong feeling with that, but `-link` seems to be more safe since with the
option javadoc tool checks if the files to be linked exist on the local
machine.)
----------------------------------------------------------------
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:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
