Utility scripts for transforming old Gradle user manual `api:...` links to the current `link:...` ones and for verifying the validity of links in the resulting HTML

checkUrlLinks.groovy

/**
 * A script that parses an HTML page at a given URL and checks that none of the
 * links point to non-existent pages.
 */
@Grab('org.jsoup:jsoup:1.11.3')
import org.jsoup.Jsoup

if (args.size() != 1) {
    println "Incorrect number of arguments!"
    println()
    println "USAGE: checkUrlLinks URL"
    System.exit(1)
}

def url = args[0]
def baseUrl = extractBaseUrl(url)
def doc = Jsoup.connect(url).get()
doc.select("a[href]")*.attributes()*.get("href").each { tryUrl(baseUrl, it) }


println "Done!"

def tryUrl(String baseUrl, String url) {
    if (url.startsWith("#")) {
        println "Ignoring internal link '${url}'"
        return
    }
    
    try {
        if (!(url =~ ~/https?:\/\//)) { url = baseUrl + (url.startsWith('/') ? url : '/' + url) }
        new URL(url).newInputStream().read()
    }
    catch (FileNotFoundException ex) {
        println "404 Page Not Found: ${url}"
    }
}

def extractBaseUrl(String url) {
    def matcher = url =~ "([a-z\\+]+://[^/]+)/"
    if (matcher) {
        return matcher[0][1]
    }
    else {
        throw new RuntimeException("$url is not a recognised URL")
    }
}

transformDocLinks.groovy

/**
 * A script that transforms the old `api:...` links in Gradle's user manual source
 * to the appropriate `link:...`.
 *
 * It creates a copy of the source Asciidoc file with the new link format. You can
 * either provide a path to the copy or accept the default: /old/path/${name}_copy.adoc.
 * Note that the default output file path assumes that the source file ends with a
 * .adoc suffix.
 *
 * The script requires an internet connection unless you run a local HTTP server to host
 * the user manual HTML pages. In that case, just change the URLs returned by the
 * `getDslRefBaseUrl()` and `getJavadocBaseUrl()` methods below.
 */
if (!(args.size() in 1..2)) {
    println "Incorrect number of arguments!"
    println()
    println "USAGE: transformDocLinks FILE [OUTFILE]"
    System.exit(1)
}

def sourceFile = new File(args[0])
def outputFile = new File(args.size() == 2 ? args[1] : args[0].replaceAll(/\.adoc$/, "_copy.adoc"))

def oldApiLinkFormat = ~/api:([\w\.]+)(?:#(\S+))?\[\]/

outputFile.text = sourceFile.text.replaceAll(oldApiLinkFormat) { match -> 
    def (className, methodSignature) = match[1..-1]
    
    def docUrl = calculateDocUrl(className, methodSignature)
    return generateAsciidocLink(docUrl, className, methodSignature)
}

println "Transformed text in ${outputFile.path}"


def getDslRefBaseUrl() { return "https://docs.gradle.org/nightly/dsl" }
def getJavadocBaseUrl() { return "https://docs.gradle.org/nightly/javadoc" }

def tryUrl(String url) {
    new URL(url).newInputStream().read()
}

def calculateDocUrl(String className, String methodSignature) {
    def docUrl
    
    try {
        // Try Groovy DSL Reference URL
        docUrl = "${dslRefBaseUrl}/${className}.html"
        if (methodSignature) docUrl += "#${className}:${transformSigForDslUrl(methodSignature)}"
        
        tryUrl(docUrl)
    }
    catch (FileNotFoundException ex) {
        // Try the Javadoc URL
        docUrl = "${javadocBaseUrl}"
        docUrl += "/${className.replace('.', '/')}.html"
        
        if (methodSignature) {
            docUrl += "#${methodSignature.replaceAll(/[\(\)]/,'-')}"
        }
        tryUrl(docUrl)
    }
    
    return docUrl
}

def generateAsciidocLink(String docUrl, String className, String methodSignature) {
    def content = new StringBuilder("link:")
    if (docUrl.startsWith(dslRefBaseUrl)) {
        docUrl = docUrl - dslRefBaseUrl
        content << '{groovyDslPath}'
    }
    else {
        docUrl = docUrl - javadocBaseUrl
        content << '{javadocPath}'
    }
    content << escapeUrlForAsciidoctor(docUrl)
    content << generateLinkText(className, methodSignature)
    return content.toString()
}

def transformSigForDslUrl(String methodSignature) {
    return transformToPropertyIfAppropriate(methodSignature).replace("...", "[]")
}

def transformToPropertyIfAppropriate(String methodSignature) {
    def matcher = methodSignature =~ /get([A-Z]\w*)\(\)/
    if (matcher) {
        def capitalizedMethodName = matcher[0][1]
        return capitalizedMethodName[0].toLowerCase() + (capitalizedMethodName.size() > 1 ? capitalizedMethodName[1..-1] : '')
    }
    else {
        return methodSignature
    }
}

def escapeUrlForAsciidoctor(String url) {
    return url.replace("...", "++...++").replace("[]", "++[]++")
}

def generateLinkText(String className, String methodSignature) {
    return removePackages("[${className}${methodSignature ? '.' + transformToPropertyIfAppropriate(methodSignature) : ''}]")
}

def removePackages (String text) {
    return text.replaceAll(/(?:[a-z]+\.)+([A-Z])/, '$1')
}