build.gradle

/*
 * Copyright 2013, The Thymeleaf Project (http://www.thymeleaf.org/)
 * 
 * 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 nz.net.ultraq.lesscss.LessCSSCompiler

import org.apache.tools.ant.filters.*
import org.gradle.api.plugins.jetty.internal.Monitor

import java.text.SimpleDateFormat

/**
 * Gradle build script for the Thymeleaf Docs project, converts the
 * documentation files, in Markdown format, into HTML and PDF formats.
 *
 * @author Emanuel Rabina
 */

/*
 * NOTE: More information about the MarkDown format and extensions that can be used:
 * http://johnmacfarlane.net/pandoc/demo/example9/pandocs-markdown.html
 */

apply plugin: 'java'
apply plugin: 'war'
apply plugin: 'jetty'

project.webAppDirName = "${buildDir}/jetty"

// These two variables should be updated when creating a new version of the docs
project.version = '3.0.0.RELEASE'
def documentDate = new Date().clearTime()
documentDate.set(
        year: 2016,
        month: Calendar.MAY,
        date: 8)

def conversions = [
        articles: ['html'],
        tutorials: ['html', 'ebook', 'pdf']
]
def docsDir      = file("${projectDir}/docs")
def imagesDir    = file("${projectDir}/images")
def scriptsDir   = file("${projectDir}/scripts")
def stylesDir    = file("${projectDir}/styles")
def templatesDir = file("${projectDir}/templates")
def srcDir       = file("${buildDir}/tmp")
def outputDir    = file("${buildDir}/site")

def docNames = [] as Set
def docTypes = [:]


buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'nz.net.ultraq.lesscss:lesscss-compiler:1.0.2'
    }
}

/**
 * Copy all docs and resources to the source dir, from where they will be fed to
 * pandoc. Also, during this copy operation markdown files will be filtered so
 * that Gradle properties are resolved in their metadata sections.
 *
 * Note that, for doc files, the name of the folder they are immediately in will
 * be considered their "document type", and this will have an influence on the
 * type of conversions that will be applied to them.
 */
task copyResources << {

    def documentVersion = new SimpleDateFormat('yyyyMMdd - dd MMMM yyyy', Locale.ENGLISH).format(documentDate)

    // Copy docs files to the src folder. For markdown files, apply property filtering and build the name-type map
    copy {
        from docsDir
        into srcDir

        filesMatching('**/*.md') {

            // We need a file path relative to the 'docs' folder
            def docFileName = (it.relativePath.toString() - ".md").replace('\\', '/')
            def docFileType = it.file.parentFile.name

            // The parent folder in some cases might be a version number (e.g. tutorials for 2.1, 3.0...) In
            // such case, we need to obtain the document type from the parent of the parent. Note three types
            // of version specifications are allowed: '2.1', '2.1.4', '2.1.x'
            if (docFileType ==~ /\d+\.\d+(\.\d+)?/ || docFileType ==~ /\d+\.\d+(\.x)?/) {
                docFileType = it.file.parentFile.parentFile.name
            }

            docNames.add(docFileName)
            docTypes.put(docFileName, docFileType)

            // Property filtering, this will replace all @gradle-properties@ (mainly used in markdown metadata)
            filter(ReplaceTokens, tokens: [
                    documentVersion: documentVersion,
                    projectVersion : project.version
            ])
        }
    }

    // Copy all resource directories straight over
    copy {
        from scriptsDir
        into "${srcDir.path}/scripts"
    }
    copy {
        from imagesDir
        into "${srcDir.path}/images"
    }

    // Copy over stylesheets, compiling LessCSS files into CSS
    copy {
        from(stylesDir) {
            exclude '**/*.less'
        }
        into "${srcDir.path}/styles"
    }

    LessCSSCompiler compiler = new LessCSSCompiler()
    fileTree(stylesDir) { include '**/*.less' }.each { lessFile ->
        def lessFileBase = lessFile.name - '.less'
        compiler.compile(lessFile, file("${srcDir.path}/styles/${lessFileBase}.css"))
    }

    // Generate output directory structure
    mkdir outputDir
    mkdir "${outputDir.path}/doc"
}

/**
 * Generate HTML versions of the Thymeleaf documentation.
 */
task generateDocsHTML(
        dependsOn: copyResources,
        description: "Generate HTML docs from Thymeleaf's markdown docs") << {

    docNames.each { docName ->
        def docType = docTypes.get(docName)

        if (conversions[docType].contains('html')) {
            println "Generating HTML doc for ${docName} (${docType})..."

            def outputFile = file("${outputDir.path}/doc/${docName}.html")
            file(outputFile.parent).mkdirs()
            execute([
                    "pandoc",
                    "--write=html5",
                    "--template=" + file("${templatesDir.path}/${docType}.html"),
                    "--toc",
                    "--toc-depth=4",
                    "--section-divs",
                    "--no-highlight",
                    "--smart",
                    "--output=" + outputFile,
                    "${srcDir.path}/${docName}.md"
            ])
        }
    }

    // Copy over resources needed for the HTML docs
    copy {
        from srcDir
        into "${outputDir.path}/doc"
        exclude '**/*.md'
    }
}

/**
 * Generate e-books of the Thymeleaf documentation.
 */
task generateDocsEbook(
        dependsOn: copyResources,
        description: "Generate e-books from Thymeleaf's markdown docs") << {

    // Currently only limited to tutorials
    docNames.each { docName ->
        def docType = docTypes.get(docName)

        if (conversions[docType].contains('ebook')) {
            println "Generating E-Book docs for ${docName} (${docType})..."

            def epubOutputFile = file("${outputDir.path}/doc/${docName}.epub")
            def mobiOutputFile = file("${outputDir.path}/doc/${docName}.mobi")
            file(epubOutputFile.parent).mkdirs()

            def inputFile = file("${srcDir.path}/${docName}.md")

            execute([
                    "pandoc",
                    "--write=epub",
                    "--template=" + file("${templatesDir.path}/${docType}.epub"),
                    "--toc",
                    "--toc-depth=4",
                    "--section-divs",
                    "--smart",
                    "--output=" + epubOutputFile,
                    inputFile
            ], file(inputFile.parent))  // We need to set the working dir in order for pandoc to find images
            execute([
                    "ebook-convert",
                    epubOutputFile,
                    mobiOutputFile
            ])
        }
    }
}

/**
 * Jetty configuration, including a fix for Jetty not stopping, obtained from
 * the bug report here: http://issues.gradle.org/browse/GRADLE-2263
 */
[jettyRun, jettyStop]*.stopPort = 8081
[jettyRun, jettyStop]*.stopKey = 'stop'
jettyRun.doLast {

    /*
     * THIS IS A WORKAROUND! THE CURRENT VERSION OF THIS TASK DOESN'T START A WATCHER IN DAEMON MODE
     *
     * If starting the monitor fails, it may be because the jetty task was updated to fix this issue
     * When that happens, we shouldn't need the custom task any more
     *
     * Copied From: AbstractJettyRunTask
     */
    if (getStopPort() != null && getStopPort() > 0 && getStopKey() != null) {
        Monitor monitor = new Monitor(getStopPort(), getStopKey(), server.getProxiedObject());
        monitor.start();
    }
}

/**
 * Generate PDF versions of the Thymeleaf documentation.  Uses a Jetty server to
 * host the HTML documents, and wkhtmltopdf which uses the server to read files
 * via the http:// protocol (otherwise the same-origin restriction kicks in, as
 * do some file:// bugs on Windows) and saves them as PDF documents.
 */
task generateDocsPDF(
        dependsOn: generateDocsHTML,
        description: "Generate PDF documents from Thymeleaf's HTML docs") << {

    // Copy over the HTML documents into a directory from which we can host them
    // using the Jetty server
    copy {
        from "${outputDir.path}/doc"
        into "${project.webAppDirName}"
    }

    jettyRun.daemon = true
    jettyRun.execute()

    // Generate the PDF documents from the modified HTML documents
    fileTree(webAppDirName) { include '*/**/*.html' }.each { docFile ->

        def folderBase = relativePath(file(webAppDirName))
        def docName = (relativePath(docFile).substring(folderBase.length() + 1) - ".html")
        def docType = docTypes.get(docName)

        if (conversions[docType].contains('pdf')) {
            println "Generating PDF doc for ${docName} (${docType})..."

            execute([
                    "wkhtmltopdf",
                    "--print-media-type",
                    "--dpi", "300",
                    "--javascript-delay", "1000",
                    "--margin-bottom", "15",
                    "--footer-spacing", "5",
                    "--footer-font-size", "8",
                    "--footer-font-name", "'Ubuntu'",
                    "--footer-right", "Page [page] of [topage]",
                    "--quiet",
                    "http://localhost:8080/thymeleaf-docs/${docName}.html",
                    file("${outputDir.path}/doc/${docName}.pdf")
            ])
        }
    }

    jettyStop.execute()
}

/**
 * Generate HTML, E-book and PDF versions of the Thymeleaf documentation.
 */
task generateDocs(
        dependsOn: [generateDocsHTML, generateDocsEbook, generateDocsPDF],
        description: "Generate HTML, E-book and PDF documents from Thymeleaf's markdown docs") {

    // Just an aggregator task
}

/**
 * Execute the given command and wait for the process to complete.
 *
 * @param command
 */
def execute(command, workingDir = projectDir) {
    def proc = command.execute(null, workingDir)
    proc.waitForProcessOutput(System.out, System.err)
    if (proc.exitValue() > 0) {
        println "${proc.err.text}"
    }
}