From 3d04bd8d336526e922939ee10bd999894c488498 Mon Sep 17 00:00:00 2001 From: Puneet Behl Date: Mon, 20 Nov 2023 13:31:53 +0530 Subject: [PATCH] Build Documentation --- build.gradle | 75 ++++++++++- buildSrc/build.gradle | 5 +- gradle/documentation.gradle | 137 --------------------- gradle/libs.versions.toml | 7 +- settings.gradle | 4 +- src/main/docs/resources/styles/layout.html | 119 ++++++++++++++++++ 6 files changed, 201 insertions(+), 146 deletions(-) delete mode 100644 gradle/documentation.gradle create mode 100644 src/main/docs/resources/styles/layout.html diff --git a/build.gradle b/build.gradle index 6f1f1b8b..e7d4cc6e 100644 --- a/build.gradle +++ b/build.gradle @@ -1,12 +1,12 @@ plugins { id 'groovy' id 'io.github.gradle-nexus.publish-plugin' + id "org.asciidoctor.jvm.convert" version "4.0.0-alpha.1" } version = projectVersion repositories { - mavenLocal() mavenCentral() maven { url 'https://repo.grails.org/grails/core' } } @@ -34,6 +34,79 @@ if(isReleaseVersion) { } } +configurations { + documentation.extendsFrom compileClasspath +} + +dependencies { + documentation libs.groovy + documentation libs.groovy.templates + documentation libs.groovy.ant + documentation libs.groovy.dateutil + documentation libs.groovy.cli.picocli + +} + +tasks.withType(Groovydoc) { + group = "documentation" + docTitle = "${project.title} - ${project.version}" + destinationDir = project.file("build/docs/api") + def files = [] + project.rootProject.subprojects + .findAll { !it.name != 'docs' && !it.name.startsWith('examples') } + .each { subproject -> + if(subproject.file('src/main/groovy').exists()) { + files += subproject.files("src/main/groovy") + } + } + if(project.file('src/main/groovy').exists()) { + files += project.files("src/main/groovy") + } + source = files + classpath = configurations.documentation +} + +task publishGuide(type: grails.doc.gradle.PublishGuide) { + group = "documentation" + description = 'Generate Guide' + dependsOn ["groovydoc"] + + targetDir = project.file("${buildDir}/docs") + sourceRepo = "https://github.com/${githubSlug}/edit/${githubBranch}/src/main/docs" + sourceDir = new File(projectDir, "src/main/docs") + propertiesFiles = [ new File(rootProject.projectDir, "gradle.properties") ] + asciidoc = true + resourcesDir = project.layout.projectDirectory.dir("src/main/docs/resources").asFile + properties = [ + 'safe': 'UNSAFE', + 'version': project.version, + 'subtitle': project.projectDesc, + 'api': '../api', + 'sourceDir': rootProject.projectDir.absolutePath, + 'sourcedir': rootProject.projectDir.absolutePath, + 'javaee': 'https://docs.oracle.com/javaee/7/api/', + 'javase': 'https://docs.oracle.com/en/java/javase/11/docs/api/', + 'groovyapi': "https://docs.groovy-lang.org/${libs.versions.groovy.asProvider().get()}/html/gapi/", + 'grailsapi': "https://docs.grails.org/${libs.versions.grails.asProvider().get()}/api/", + 'gormapi': "https://gorm.grails.org/${libs.versions.gorm.get()}/api/", + 'springapi': "https://docs.spring.io/spring/docs/${libs.versions.spring.get()}/javadoc-api/" + ] + doLast { + ant.move(file:"${project.buildDir}/docs/guide/single.html", + tofile:"${project.buildDir}/docs/guide/index.html", overwrite:true) + new File(project.buildDir, "docs/index.html").text = ''' + + + + + + + + +''' + } +} + subprojects { version = rootProject.version diff --git a/buildSrc/build.gradle b/buildSrc/build.gradle index 449d446f..44a65120 100644 --- a/buildSrc/build.gradle +++ b/buildSrc/build.gradle @@ -1,8 +1,6 @@ plugins { - id 'groovy-gradle-plugin' id 'maven-publish' - } repositories { @@ -11,10 +9,9 @@ repositories { } dependencies { - implementation libs.nexus.publish.gradle.plugin implementation libs.grails.gradle.plugin implementation libs.grails.views.gradle.plugin implementation libs.groovydoc.gradle.plugin - + implementation libs.grails.docs } \ No newline at end of file diff --git a/gradle/documentation.gradle b/gradle/documentation.gradle deleted file mode 100644 index 8f62ecf1..00000000 --- a/gradle/documentation.gradle +++ /dev/null @@ -1,137 +0,0 @@ -/* - README - ====== - This file is not used at the moment. Should Guide/API-docs generation be moved to its on project? - (Like the grails/gorm-docs project for grails/grails-data-mapping) -*/ - -def DOCUMENTATION_GROUP = 'Documentation' - -def commonGithubOrg = 'grails' -def commonGithubSlug = 'grails-common-build' -def commonBranch = 'master' -def docResourcesDir = "${buildDir}/resources/${commonGithubSlug}-${commonBranch}/src/main/resources" - -tasks.register('remoteDocResources', Copy) { - - group = DOCUMENTATION_GROUP - description = 'Downloads common documentation resources and unzips them to build folder' - - from zipTree("https://github.com/${commonGithubOrg}/${commonGithubSlug}/archive/${commonBranch}.zip") - into docResourcesDir -} - -tasks.register('localDocResources', Copy) { - - group = DOCUMENTATION_GROUP - description = 'Copy local resources to build folder' - - from 'src/main/docs/resources' - into docResourcesDir - onlyIf { project.file('src/main/docs/resources').exists() } -} - -configurations { - documentation -} - -dependencies { - if (configurations.find { it.name == 'documentation' }) { - documentation libs.picocli - documentation libs.jansi - documentation libs.jline2 - documentation libs.javaparser.core - documentation libs.groovy - documentation libs.groovy.ant - documentation libs.groovy.cli.picocli - } -} - -//groovydoc.classpath += configurations.documentation - -tasks.withType(Groovydoc).configureEach { - - group = DOCUMENTATION_GROUP - - docTitle = "${project.title} - ${project.version}" - destinationDir = project.file('build/docs/api') - - // Add the sources of all subprojects (except from the examples directory) - def files = [] - rootProject.subprojects - .findAll { it.projectDir.parentFile.name != 'examples' && it.file('src/main/groovy').exists() } - .each { sp -> source = sp.files('src/main/groovy') } - - classpath += configurations.documentation -} - -tasks.register('copyHtmlIndex', Copy) { - - group = DOCUMENTATION_GROUP - description = 'Copy index.html to build folder' - - from "$buildDir/docs/guide/single.html" - into "$buildDir/docs/guide/" - rename 'single.html', 'index.html' - //overwrite true - -/* - dependsOn tasks.named('prepareDocResources') - source file(project.buildDir, 'docs/guide/single.html') - destinationDirectory file(project.buildDir, 'docs/guide/') - include 'index.html' - rename 'index.html', 'single.html' -*/ -} - -tasks.register('guide', grails.doc.gradle.PublishGuide) { - - group = DOCUMENTATION_GROUP - description = 'Generate Guide' - - targetDir = project.file("${buildDir}/docs") - sourceRepo = "https://github.com/${githubSlug}/edit/${githubBranch}/src/main/docs" - sourceDir = new File(rootProject.projectDir, 'src/main/docs') - propertiesFiles = [ new File(rootProject.projectDir, 'gradle.properties') ] - asciidoc = true - resourcesDir = project.file(docResourcesDir) - properties = [ - 'safe': 'UNSAFE', - 'version': project.version, - 'subtitle': project.projectDesc, - 'api': '../api', - 'sourceDir': rootProject.projectDir.absolutePath, - 'sourcedir': rootProject.projectDir.absolutePath, - 'javaee': 'https://docs.oracle.com/javaee/7/api/', - 'javase': 'https://docs.oracle.com/en/java/javase/11/docs/api/', - 'groovyapi': "https://docs.groovy-lang.org/${libs.versions.groovy}/html/gapi/", - 'grailsapi': "https://docs.grails.org/${libs.versions.grails}/api/", - 'gormapi': "https://gorm.grails.org/${libs.versions.gorm}/api/", - 'springapi': "https://docs.spring.io/spring/docs/${libs.versions.spring}/javadoc-api/" - ] - doLast { - ant.move(file: "${project.buildDir}/docs/guide/single.html", - tofile: "${project.buildDir}/docs/guide/index.html", overwrite: true) - new File(project.buildDir, 'docs/index.html').text = '' - } -} - -/* -tasks.register('docs') { - - group = DOCUMENTATION_GROUP - from ['groovydoc', 'guide'] -} -*/ - -def assembleTask = project.tasks.findByName("assemble") -if(assembleTask == null) { - tasks.register('assemble', Zip) { - - from groovydoc - from guide - - archiveBaseName = "${project.name}-${project.version}" - destinationDirectory = new File(project.buildDir, 'distributions') - } -} \ No newline at end of file diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index ee781d20..7118b8a2 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -19,12 +19,15 @@ spock = '2.1-groovy-3.0' spring = '5.3.30' [libraries] +grails-docs = { module = "org.grails:grails-docs", version.ref = "grails" } gpars = { module = 'org.codehaus.gpars:gpars', version.ref = 'gpars' } gorm = { module = 'org.grails:grails-datastore-gorm', version.ref = 'gorm' } gorm-test = { module = 'org.grails:grails-datastore-gorm-test', version.ref = 'gorm' } groovy = { module = 'org.codehaus.groovy:groovy', version.ref = 'groovy' } -#groovy-ant = { module = 'org.codehaus.groovy:groovy-ant', version.ref = 'groovy' } -#groovy-cli-picocli = { module = 'org.codehaus.groovy:groovy-cli-picocli', version.ref = 'groovy' } +groovy-templates = { module = 'org.codehaus.groovy:groovy-templates', version.ref = 'groovy' } +groovy-ant = { module = 'org.codehaus.groovy:groovy-ant', version.ref = 'groovy' } +groovy-dateutil = { module = 'org.codehaus.groovy:groovy-dateutil', version.ref = 'groovy' } +groovy-cli-picocli = { module = 'org.codehaus.groovy:groovy-cli-picocli', version.ref = 'groovy' } jansi = { module = 'org.fusesource.jansi:jansi', version.ref = 'jansi' } javaparser-core = { module = 'com.github.javaparser:javaparser-core', version.ref = 'javaparser' } javax-annotation-api = { module = 'javax.annotation:javax.annotation-api', version.ref = 'javax-annotation' } diff --git a/settings.gradle b/settings.gradle index 59def7bd..832e92dc 100644 --- a/settings.gradle +++ b/settings.gradle @@ -26,5 +26,5 @@ include 'grails-plugin-async' include 'grails-plugin-events' // examples -include 'pubsub-demo' -project(':pubsub-demo').projectDir = new File(settingsDir, 'examples/pubsub-demo') +include 'examples-pubsub-demo' +project(':examples-pubsub-demo').projectDir = new File(settingsDir, 'examples/pubsub-demo') diff --git a/src/main/docs/resources/styles/layout.html b/src/main/docs/resources/styles/layout.html new file mode 100644 index 00000000..fdff713a --- /dev/null +++ b/src/main/docs/resources/styles/layout.html @@ -0,0 +1,119 @@ + + + + ${title.encodeAsHtml()} + + + + + + + + + + + + + + + + + +
+
+ +
+

${title.encodeAsHtml()}

+

+

${subtitle?.encodeAsHtml()}

+

Version: ${version}

+ +
+ + ${content} +
+ 		+
+ <% if(toc){ %> +
+

Table of Contents

+ <% + sectionWriter = { lvl, section, topSection, prefix -> + if (single) { + %> +
$prefix${section.title?.encodeAsHtml()}
+ <% + } + else { + %> +
$prefix${section.title?.encodeAsHtml()}
+ <% + } + + lvl++ + section.children.eachWithIndex { s, j -> + sectionWriter.call(lvl, s, topSection, prefix + '.' + (j + 1)) + } + } + + toc.children.eachWithIndex { topSection, i -> + sectionWriter.call(0, topSection, topSection, i + 1) + } + %> +
+
+ <% } %> +
+
+ + + + + + \ No newline at end of file