docs.gradle

/*
 * Copyright 2010 the original author or authors.
 *
 * Licensed 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.
 */
import org.gradle.build.docs.UserGuideTransformTask
import org.gradle.build.docs.ExtractSnippetsTask
import org.gradle.build.docs.AssembleSamplesDocTask
import org.gradle.build.docs.Docbook2Xhtml
import org.gradle.build.docs.dsl.docbook.AssembleDslDocTask
import org.gradle.build.docs.dsl.ExtractDslMetaDataTask
import org.gradle.internal.os.OperatingSystem

apply plugin: 'base'
apply plugin: 'pegdown'
apply plugin: 'jsoup'

configurations {
    userGuideStyleSheets
    userGuideTask
}

dependencies {
    userGuideTask 'xalan:xalan:2.7.1', 'xerces:xercesImpl:2.9.1'
    userGuideTask module('xhtmlrenderer:xhtmlrenderer:R8rc1') {
        dependency 'itext:itext:2.0.8@jar'
    }
    userGuideTask 'xslthl:xslthl:2.0.1@jar'

    userGuideStyleSheets 'docbook:docbook-xsl:1.75.2@zip'
}

ext {
    srcDocsDir = file('src/docs')
    userguideSrcDir = new File(srcDocsDir, 'userguide')
    cssSrcDir = new File(srcDocsDir, 'css')
    dslSrcDir = new File(srcDocsDir, 'dsl')
    docsDir = file("$buildDir/docs")
    userguideDir = new File(docsDir, 'userguide')
    distDocsDir = new File(buildDir, 'distDocs')
    samplesDir = file("$buildDir/samples")
    docbookSrc = new File(project.buildDir, 'src')
    samplesSrcDir = file('src/samples')
}

ext.outputs = [:]
outputs.samples = files(samplesDir) {
    builtBy 'samples'
}
outputs.distDocs = files(distDocsDir) {
    builtBy 'distDocs'
}
outputs.docs = files(docsDir) {
    builtBy 'javadoc', 'groovydoc', 'userguide', 'dslHtml', 'releaseNotes'
}

tasks.withType(Docbook2Xhtml) {
    dependsOn userguideStyleSheets
    classpath = configurations.userGuideTask
    stylesheetsDir = userguideStyleSheets.destinationDir
}
tasks.withType(UserGuideTransformTask) {
    dependsOn samples, dslDocbook
    snippetsDir = samples.snippetsDir
    linksFile = dslDocbook.linksFile
    websiteUrl = 'http://www.gradle.org'
    
    if (name in ["pdfUserguideDocbook", "userguideFragmentSrc"]) {
        // These will only be valid for releases, but that's ok
        javadocUrl = "http://www.gradle.org/doc/${->version}/javadoc"
        groovydocUrl = "http://www.gradle.org/doc/${->version}/groovydoc"
        dsldocUrl = "http://www.gradle.org/doc/${->version}/dsl"
    } else {
        javadocUrl = '../javadoc'
        groovydocUrl = '../groovydoc'
        dsldocUrl = '../dsl'
    }
}
tasks.withType(AssembleDslDocTask) {
    classDocbookDir = dslSrcDir
}

task samples(type: ExtractSnippetsTask) {
    source samplesSrcDir
    exclude 'userguideOutput/**'
    exclude 'userguide/tutorial/antLoadfileResources/**'
    exclude '**/readme.xml'
    destDir = samplesDir
    snippetsDir = new File(buildDir, 'snippets')
    doLast {
        copy {
            from samplesSrcDir
            into samplesDir
            include 'userguide/tutorial/antLoadfileResources/**'
        }
    }
}

task userguideStyleSheets(type: Copy) {
    File stylesheetsDir = new File(srcDocsDir, 'stylesheets')
    into new File(buildDir, 'stylesheets')
    from(stylesheetsDir) {
        include '*.xsl'
    }
    from(cssSrcDir) {
        include '*.css'
    }
    from(zipTree(configurations.userGuideStyleSheets.singleFile)) {
        // Remove the prefix
        eachFile { fcd -> fcd.path = fcd.path.replaceFirst('^docbook-xsl-[0-9\\.]+/', '') }
    }
}

task samplesDocbook(type: AssembleSamplesDocTask) {
    source samplesSrcDir
    include '**/readme.xml'
    destFile = new File(docbookSrc, 'samplesList.xml')
}

task samplesDocs(type: Docbook2Xhtml) {
    source samplesDocbook
    destFile = new File(samples.destDir, 'readme.html')
    stylesheetName = 'standaloneHtml.xsl'
}

task dslMetaData(type: ExtractDslMetaDataTask) {  //TODO SF: parseSourceCode
    source { groovydoc.source }
    destFile = new File(docbookSrc, 'dsl-meta-data.bin')
}

task dslDocbook(type: AssembleDslDocTask, dependsOn: [dslMetaData]) {
    inputs.files fileTree(dir: dslSrcDir, includes: ['*.xml'])
    sourceFile = new File(dslSrcDir, 'dsl.xml')
    classMetaDataFile = dslMetaData.destFile
    pluginsMetaDataFile = new File(dslSrcDir, 'plugins.xml')
    destFile = new File(docbookSrc, 'dsl.xml')
    linksFile = new File(docbookSrc, 'api-links.bin')
}

task dslStandaloneDocbook(type: UserGuideTransformTask, dependsOn: [dslDocbook]) {
    sourceFile = dslDocbook.destFile
    destFile = new File(docbookSrc, 'dsl-standalone.xml')
    dsldocUrl = '.'
}

task dslHtml(type: Docbook2Xhtml) {
    source dslStandaloneDocbook
    destDir = new File(docsDir, 'dsl')
    stylesheetName = 'dslHtml.xsl'
    resources = fileTree(cssSrcDir) {
        include '*.css'
    } + fileTree(dslSrcDir) {
        include '*.js'
    }
}

// This is used in the distribution and for the online version
task userguideDocbook(type: UserGuideTransformTask, dependsOn: [samples, samplesDocbook]) {
    destFile = new File(docbookSrc, 'userguide.xml')
}

// This is used for the PDF, where we need absolute links to the javadoc etc.
task pdfUserguideDocbook(type: UserGuideTransformTask, dependsOn: [samples, samplesDocbook]) {
    destFile = new File(docbookSrc, 'remoteUserguide.xml')
}

configure([userguideDocbook, pdfUserguideDocbook]) {
    // The master userguide.xml pulls these files in via xi:include, making them input
    inputs.files fileTree(dir: userguideSrcDir, includes: ['*.xml'])

    sourceFile new File(userguideSrcDir, 'userguide.xml')
    websiteUrl 'http://www.gradle.org'
}

task userguideHtml(type: Docbook2Xhtml) {
    source userguideDocbook
    destDir = userguideDir
    stylesheetName = 'userGuideHtml.xsl'
    resources = fileTree(userguideSrcDir) {
        include 'img/*.png'
    }
    resources += fileTree(cssSrcDir) {
        include '*.css'
    }
}

task userguideSingleHtml(type: Docbook2Xhtml) {
    source userguideDocbook
    destFile = new File(userguideDir, 'userguide_single.html')
    stylesheetName = 'userGuideSingleHtml.xsl'
    resources = fileTree(userguideSrcDir) {
        include 'img/*.png'
    }
    resources += fileTree(cssSrcDir) {
        include '*.css'
    }
}

task pdfUserguideXhtml(type: Docbook2Xhtml) {
    source pdfUserguideDocbook
    destFile = new File(buildDir, 'tmp/userguidePdf/userguidePdf.html')
    stylesheetName = 'userGuidePdf.xsl'
    resources = fileTree(userguideSrcDir) {
        include 'img/*.png'
    }
    resources += fileTree(cssSrcDir) {
        include '*.css'
    }
}

task userguidePdf(type: Xhtml2Pdf, dependsOn: pdfUserguideXhtml) {
    inputs.dir cssSrcDir
    sourceFile = pdfUserguideXhtml.destFile
    destFile = new File(userguideDir, 'userguide.pdf')
    classpath = configurations.userGuideTask
}

def javaApiUrl = "http://docs.oracle.com/javase/1.5.0/docs/api/"
def groovyApiUrl = "http://groovy.codehaus.org/gapi/"

task javadoc(type: Javadoc) {
    ext.stylesheetFile = file("src/docs/css/javadoc.css")
    inputs.file stylesheetFile

    group = 'documentation'
    options.encoding = 'utf-8'
    options.docEncoding = 'utf-8'
    options.charSet = 'utf-8'
    options.addStringOption "stylesheetfile", stylesheetFile.absolutePath
    source groovyProjects().collect {project -> project.sourceSets.main.allJava }
    destinationDir = new File(docsDir, 'javadoc')
    classpath = files(groovyProjects().collect {project -> [project.sourceSets.main.compileClasspath, project.sourceSets.main.output] })
    include 'org/gradle/api/**'
    include 'org/gradle/*'
    include 'org/gradle/external/javadoc/**'
    include 'org/gradle/process/**'
    include 'org/gradle/plugins/**'
    include 'org/gradle/testfixtures/**'
    include 'org/gradle/tooling/**'
    exclude '**/internal/**'
    options.links(javaApiUrl, groovyApiUrl, "http://maven.apache.org/ref/2.2.1/maven-core/apidocs",
        "http://maven.apache.org/ref/2.2.1/maven-model/apidocs")
    doFirst {
        title = "Gradle API $version"
    }
}

task configureGroovydoc {
    doFirst {
        project.configure(groovydoc) {
            [javaApiUrl, groovyApiUrl].each {
                link(it, *(new URL("$it/package-list").text.tokenize("\n")))
            }
            docTitle = "Gradle API $version"
            windowTitle = "Gradle API $version"
            footer = "Gradle API $version"
        }
    }
}

task groovydoc(type: Groovydoc, dependsOn: configureGroovydoc) {
    group = 'documentation'
    source groovyProjects().collect {project -> project.sourceSets.main.groovy + project.sourceSets.main.java }
    destinationDir = new File(docsDir, 'groovydoc')
    classpath = javadoc.classpath
    includes = javadoc.includes
    excludes = javadoc.excludes
    doFirst {
        windowTitle = "Gradle API $version"
        docTitle = windowTitle
    }
    groovyClasspath = project(':core').configurations.groovy
    doLast {
        def index = new File(destinationDir, "index.html")
        index.text = index.text.replace("{todo.title}", windowTitle) // workaround groovydoc bug
    }

    gradle.taskGraph.whenReady {
        if (it.hasTask(groovydoc)) {
            def systemCharset = java.nio.charset.Charset.defaultCharset().name()
            if (systemCharset != "UTF-8") {
                if (!isSnapshot) {
                    throw new InvalidUserDataException("Cannot run $groovydoc.name task unless system charset is UTF-8 (it's $systemCharset, set -Dfile.encoding=UTF-8) in GRADLE_OPTS")
                } else {
                    logger.warn("Groovydoc will be generated in this build, but the default character encoding is '$systemCharset'. It should be 'UTF-8'. This is ok for a non release build.")
                }
            }
        }
    }
}

task checkstyleApi(type: Checkstyle) {
    source javadoc.source
    configFile = file("$checkstyleConfigDir/checkstyle-api.xml")
    classpath = files()
    reports.xml.destination = file("$checkstyle.reportsDir/checkstyle-api.xml")
}

task userguideFragmentSrc(type: UserGuideTransformTask, dependsOn: [userguideStyleSheets, samples]) {
    tags << 'standalone'
    sourceFile = new File(userguideSrcDir, 'installation.xml')
    destFile = new File(docbookSrc, 'installation.xml')
}

task distDocs(type: Docbook2Xhtml) {
    source userguideFragmentSrc
    destFile = new File(distDocsDir, 'getting-started.html')
    stylesheetName = 'standaloneHtml.xsl'
}

task userguide {
    dependsOn userguideHtml, userguideSingleHtml, userguidePdf
    description = 'Generates the userguide'
    group = 'documentation'
}

task docs {
    dependsOn javadoc, groovydoc, userguide, distDocs, samplesDocs, dslHtml
    description = 'Generates all documentation'
    group = 'documentation'
}

task docsZip(type: Zip) {
    from project.outputs.docs
}

import org.gradle.plugins.pegdown.PegDown
import org.gradle.plugins.jsoup.Jsoup

task editReleaseNotes() << {
    Class.forName("java.awt.Desktop").newInstance().edit(file("src/docs/release/notes.md"))
}

task releaseNotesMarkdown(type: PegDown) {
    source "src/docs/release/notes.md"
    destination "$buildDir/release-notes/notes-raw.html"
}

task decorateReleaseNotes(type: Jsoup) {
    source releaseNotesMarkdown
    destination "$buildDir/release-notes/notes-decorated.html"
    
    inputs.file "release-notes-transform.gradle"
    apply from: "release-notes-transform.gradle"
}

import org.apache.tools.ant.filters.*
task releaseNotes(type: Copy) {
    ext.fileName = "release-notes.html"
    into "$docsDir"
    from decorateReleaseNotes, {
        rename ".+", "release-notes.html"
        doFirst {
            owner.filter(ReplaceTokens, tokens: [version: project.version.toString()])
        }
    }
}

task viewReleaseNotes(dependsOn: releaseNotes) << {
    Class.forName("java.awt.Desktop").newInstance().browse(new File(releaseNotes.destinationDir, releaseNotes.fileName).toURI())
}

class Xhtml2Pdf extends DefaultTask {
    @InputFile
    File sourceFile

    @OutputFile
    File destFile

    @InputFiles
    FileCollection classpath

    @TaskAction
    def transform() {
        def uris = classpath.files.collect {it.toURI().toURL()}
        def classloader = new URLClassLoader(uris as URL[], getClass().classLoader)
        def renderer = classloader.loadClass('org.xhtmlrenderer.pdf.ITextRenderer').newInstance()
        renderer.setDocument(sourceFile)
        renderer.layout()
        destFile.withOutputStream {
            renderer.createPDF(it)
        }
    }
}