TLDDoc Builder Gradle Plugin

The TLDDoc Builder Gradle plugin lets you run the Tag Library Documentation Generator tool in order to generate documentation for the JSP Tag Library Descriptor (TLD) files in your project.

The plugin has been successfully tested with Gradle 4.10.2.

Usage

To use the plugin, include it in your build script:

buildscript {
    dependencies {
        classpath group: "com.liferay", name: "com.liferay.gradle.plugins.tlddoc.builder", version: "1.3.3"
    }

    repositories {
        maven {
            url "https://repository-cdn.liferay.com/nexus/content/groups/public"
        }
    }
}

There are two TLDDoc Builder Gradle plugins you can apply to your project:

  • Apply the TLDDoc Builder Plugin to generate tag library documentation for your project:

    apply plugin: "com.liferay.tlddoc.builder"
    
  • Apply the App TLDDoc Builder Plugin in a parent project to generate the tag library documentation as a single, combined HTML document for an application that spans different subprojects, each one representing a different component of the same application:

    apply plugin: "com.liferay.app.tlddoc.builder"
    

Since the plugin automatically resolves the Tag Library Documentation Generator library as a dependency, you must configure a repository that hosts the library and its transitive dependencies. The Liferay CDN repository hosts them all:

repositories {
    maven {
        url "https://repository-cdn.liferay.com/nexus/content/groups/public"
    }
}

TLDDoc Builder Plugin

The plugin adds three tasks to your project:

NameDepends OnTypeDescription
copyTLDDocResources-CopyCopies the tag library documentation resources from src/main/tlddoc to the destination directory of the tlddoc task.
tlddoccopyTLDDocResources, validateTLDTLDDocTaskGenerates the tag library documentation.
validateTLD-ValidateSchemaTaskValidates the TLD files in the project.

The tlddoc task is automatically configured with sensible defaults, depending on whether the java plugin is applied:

Property NameDefault Value with the java plugin
destinationDir${project.docsDir}/tlddoc
includes["**/*.tld"]
sourceproject.sourceSets.main.resources.srcDirs

The validateTLD task is also automatically configured with sensible defaults, depending on whether the java plugin is applied:

Property NameDefault Value
includes

If the java plugin is applied: ["**/*.tld"]

Otherwise: []

source

If the java plugin is applied: project.sourceSets.main.resources.srcDirs

Otherwise: null

By default, the tlddoc task generates the documentation for all the TLD files that are found in the resources directories of the main source set. The documentation files are saved in build/docs/tlddoc and include the files copied from src/main/tlddoc.

The copyTLDDocResources task lets you add references to images and other resources directly in the TLD files. For example, if the project includes an image called breadcrumb.png in the src/main/tlddoc/images directory, you can reference it in a TLD file contained in the src/main/resources directory:

<description>Hello World <![CDATA[<img src="../images/breadcrumb.png"]]></description>

App TLDDoc Builder Plugin

In order to use the App TLDDoc Builder plugin, it is required to apply the com.liferay.app.tlddoc.builder plugin in a parent project (that is, a project that is a common ancestor of all the subprojects representing the various components of the app). It is also required to apply the com.liferay.tlddoc.builder plugin to all the subprojects that contain TLD files.

The App TLDDoc Builder plugin automatically applies the base plugin. It also adds three tasks to your project:

NameDepends OnTypeDescription
appTLDDoccopyAppTLDDocResources, the validateTLD tasks of the subprojectsTLDDocTaskGenerates tag library documentation for the app.
copyAppTLDDocResources-CopyCopies the tag library documentation resources defined as inputs for the copyTDLDocResources tasks of the subprojects, aggregating them into the destination directory of the appTLDDoc task.
jarAppTLDDocappTLDDocJarAssembles a JAR archive containing the tag library documentation files for this app.

The appTLDDoc task is automatically configured with sensible defaults:

Property NameDefault Value
destinationDir${project.buildDir}/docs/tlddoc
sourceThe sum of all the tlddoc.source values of the subprojects

Project Extension

The App TLDDoc Builder plugin exposes the following properties through the extension named appTLDDocBuilder:

Property NameTypeDefault ValueDescription
subprojectsSet<Project>project.subprojectsThe subprojects to include in the tag library documentation of the app.

The same extension exposes the following methods:

MethodDescription
AppTLDDocBuilderExtension subprojects(Iterable<Project> subprojects)Include additional projects in the tag library documentation of the app.
AppTLDDocBuilderExtension subprojects(Project... subprojects)Include additional projects in the tag library documentation of the app.

Tasks

TLDDocTask

Tasks of type TLDDocTask extend JavaExec, so all its properties and methods, such as args and maxHeapSize, are available. They also have the following properties set by default:

Property NameDefault Value
argsTag Library Documentation Generator command line arguments
classpathproject.configurations.tlddoc
main"com.sun.tlddoc.TLDDoc"
maxHeapSize"256m"

The TLDDocTask class is also very similar to SourceTask, which means it provides a source property and lets you specify include and exclude patterns.

Task Properties

Property NameTypeDefault ValueDescription
destinationDirFilenullThe directory where the tag library documentation files are saved.
excludesSet<String>[]The TLD file patterns to exclude.
includesSet<String>[]The TLD file patterns to include.
sourceFileTree[]The TLD files to generate documentation for, after the include and exclude patterns have been applied.
xsltDirFilenullThe directory that contains the custom XSLT stylesheets used by the Tag Library Documentation Generator to produce the final documentation files. It sets the -xslt argument.

The properties of type File support any type that can be resolved by project.file.

Task Methods

The methods available for TLDDocTask are exactly the same as the one defined in the SourceTask class.

ValidateSchemaTask

Tasks of type ValidateSchemaTask extend SourceTask, so all its properties and methods, such as include and exclude, are available.

Tasks of this type invoke the schemavalidate Ant task in order to validate XML files described by an XML schema.

Task Properties

Property NameTypeDefault ValueDescription
dtdDisabledbooleanfalseWhether to disable DTD support.
fullCheckingbooleantrueWhether to enable full schema checking.
lenientbooleanfalseWhether to only check if the XML document is well-formed.
xmlParserClassNameStringnullThe class name of the XML parser to use.
xmlParserClasspathFileCollectionnullThe classpath with the XML parser.

It is possible to use Closures and Callables as values for the String properties to defer evaluation until task execution.

Additional Configuration

There are additional configurations that can help you use the TLDDoc Builder.

Tag Library Documentation Generator Dependency

By default, the plugin creates a configuration called tlddoc and adds a dependency to the 1.3 version of the Tag Library Documentation Generator. It is possible to override this setting and use a specific version of the tool by manually adding a dependency to the tlddoc configuration:

dependencies {
    tlddoc group: "taglibrarydoc", name: "tlddoc", version: "1.3"
}
« TLD Formatter Gradle PluginWhip Gradle Plugin »
Este artigo foi útil?
Utilizadores que acharam útil: 0 de 0