lucene/gradle/render-javadoc.gradle

/*
 * 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.
 */

// generate javadocs by using Ant javadoc task

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."
      group "documentation"

      ext {
        linksource = "no"
        linkJUnit = false
        linkHref = []
      }

      dependsOn sourceSets.main.compileClasspath

      inputs.files { sourceSets.main.java.asFileTree }
      outputs.dir project.javadocRoot

      def libName = project.path.startsWith(":lucene") ? "Lucene" : "Solr"
      def title = "${libName} ${project.version} ${project.name} API".toString()

      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)
          }

          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 (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)
          }

          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) {
    renderJavadoc {
      dependsOn ':lucene:core:renderJavadoc'
      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: "")
      }
    }
  }
}

configure(subprojects.findAll { it.path.startsWith(':lucene:analysis') }) {
  plugins.withType(JavaPlugin) {
    ext {
      javadocDestDir = "${javadocRoot}/analyzers-${project.name}"
    }

    renderJavadoc {
      if (project.path != ':lucene:analysis:common') {
        dependsOn ':lucene:analysis:common:renderJavadoc'
        linkHref += [ "../analyzers-common" ]
      }
    }
  }
}

configure(project(':lucene:benchmark')) {
  plugins.withType(JavaPlugin) {
    renderJavadoc {
      [':lucene:memory',
       ':lucene:highlighter',
       ':lucene:analysis:common',
       ':lucene:queryparser',
       ':lucene:facet',
       ':lucene:spatial-extras'].collect { path ->
        dependsOn "${path}:renderJavadoc"
      }

      linkHref += [ '../memory', '../highlighter', '../analyzers-common', '../queryparser', '../facet', '../spatial-extras' ]
    }
  }
}

configure(project(':lucene:classification')) {
  plugins.withType(JavaPlugin) {
    renderJavadoc {
      [':lucene:queries', ':lucene:analysis:common', ':lucene:grouping'].collect { path ->
        dependsOn "${path}:renderJavadoc"
      }

      linkHref += ['../queries', '../analyzers-common', '../grouping']
    }
  }
}

configure(project(':lucene:demo')) {
  plugins.withType(JavaPlugin) {
    renderJavadoc {
      [':lucene:analysis:common',
       ':lucene:queryparser',
       ':lucene:queries',
       ':lucene:facet',
       ':lucene:expressions'].collect { path ->
        dependsOn "${path}:renderJavadoc"
      }
      linkHref += ['../analyzers-common', '../queryparser', '../queries', '../facet', '../expressions']

      // we link the example source in the javadocs, as it's ref'ed elsewhere
      linksource = "yes"
    }
  }
}

configure(project(':lucene:grouping')) {
  plugins.withType(JavaPlugin) {
    renderJavadoc {
      dependsOn ':lucene:queries:renderJavadoc'
      linkHref += [ '../queries' ]
    }
  }
}

configure(project(':lucene:highlighter')) {
  plugins.withType(JavaPlugin) {
    renderJavadoc {
      dependsOn ':lucene:memory:renderJavadoc'
      linkHref += [ '../memory' ]
    }
  }
}

configure(project(':lucene:monitor')) {
  plugins.withType(JavaPlugin) {
    renderJavadoc {
      [':lucene:memory', ':lucene:analysis:common', ':lucene:queryparser'].collect { path ->
        dependsOn "${path}:renderJavadoc"
      }
      linkHref += [ '../memory', '../analyzers-common', '../queryparser' ]
    }
  }
}

configure(project(':lucene:queryparser')) {
  plugins.withType(JavaPlugin) {
    renderJavadoc {
      [':lucene:queries', ':lucene:sandbox'].collect { path ->
        dependsOn "${path}:renderJavadoc"
      }
      linkHref += [ '../queries', '../sandbox' ]
    }
  }
}

configure(project(':lucene:replicator')) {
  plugins.withType(JavaPlugin) {
    renderJavadoc {
      dependsOn ':lucene:facet:renderJavadoc'
      linkHref += [ '../facet' ]
    }
  }
}

configure(project(':lucene:spatial-extras')) {
  plugins.withType(JavaPlugin) {
    renderJavadoc {
      dependsOn ':lucene:spatial3d:renderJavadoc'
      linkHref += [ '../spatial3d' ]
    }
  }
}

configure(project(':lucene:suggest')) {
  plugins.withType(JavaPlugin) {
    renderJavadoc {
      dependsOn ':lucene:analysis:common:renderJavadoc'
      linkHref += [ '../analyzers-common' ]
    }
  }
}

configure(project(':lucene:test-framework')) {
  plugins.withType(JavaPlugin) {
    renderJavadoc {
      dependsOn ':lucene:codecs:renderJavadoc'
      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.
      }
    }
  }
}

configure(project(':solr:core')) {
  plugins.withType(JavaPlugin) {
    // specialized to ONLY depend on solrj
    renderJavadoc {
      dependsOn ':solr:solrj:renderJavadoc'
      linkHref += [ '../solr-solrj' ]
    }
  }
}

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' ]
    }
  }
}

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"
    }
  }
}

configure(project(':solr:test-framework')) {
  plugins.withType(JavaPlugin) {
    renderJavadoc {
      linkJUnit = true
    }
  }
}


configure(subprojects.findAll { it.path in [':solr:solr-ref-guide', ':solr:server', ':solr:webapp']}) {
  afterEvaluate {
    project.tasks.findByPath("renderJavadoc").enabled = false
  }
}