diff --git a/CHANGELOG.md b/CHANGELOG.md index a4173a0..67c027b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,8 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added +- Default templates for README and ARTIFACT ### Changed +- Replaced Groovy templates by FreeMarker ### Deprecated diff --git a/build.gradle.kts b/build.gradle.kts index 863a158..f968103 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -39,6 +39,8 @@ dependencies { // // nexus publishing plugin // implementation("io.github.gradle-nexus:publish-plugin:1.1.0") + implementation("org.freemarker:freemarker:2.3.31") + testImplementation(kotlin("test")) } @@ -122,7 +124,7 @@ afterEvaluate { publications { create("catalog") { from(components["versionCatalog"]) - this.artifactId = "version-catalog" + artifactId = "version-catalog" pom { name.set("version-catalog") diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index 9bd6f8c..23f62d6 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -1,5 +1,5 @@ [versions] -tools = "0.10.9-kotlin-1.6.10" +tools = "0.11.0-kotlin-1.6.10" kotlin = "1.6.10" atomicfu = "0.17.0" binary-compatibility-validator = "0.8.0" diff --git a/src/main/kotlin/ru/mipt/npm/gradle/KScienceCommonPlugin.kt b/src/main/kotlin/ru/mipt/npm/gradle/KScienceCommonPlugin.kt index dbdab6e..51b22fc 100644 --- a/src/main/kotlin/ru/mipt/npm/gradle/KScienceCommonPlugin.kt +++ b/src/main/kotlin/ru/mipt/npm/gradle/KScienceCommonPlugin.kt @@ -6,6 +6,6 @@ import org.gradle.api.Project @Suppress("UNUSED_VARIABLE") public open class KScienceCommonPlugin : Plugin { override fun apply(project: Project): Unit = project.configureKScience( - KotlinVersion(1, 6, 0) + KotlinVersion(1, 6, 10) ) } diff --git a/src/main/kotlin/ru/mipt/npm/gradle/KScienceProjectPlugin.kt b/src/main/kotlin/ru/mipt/npm/gradle/KScienceProjectPlugin.kt index 6a6bb53..4829147 100644 --- a/src/main/kotlin/ru/mipt/npm/gradle/KScienceProjectPlugin.kt +++ b/src/main/kotlin/ru/mipt/npm/gradle/KScienceProjectPlugin.kt @@ -1,6 +1,5 @@ package ru.mipt.npm.gradle -import groovy.text.SimpleTemplateEngine import kotlinx.validation.ApiValidationExtension import kotlinx.validation.BinaryCompatibilityValidatorPlugin import org.gradle.api.Plugin @@ -54,7 +53,8 @@ public class KSciencePublishingExtension(public val project: Project) { } } - @Suppress("UNUSED_VARIABLE") private val release by project.tasks.creating { + @Suppress("UNUSED_VARIABLE") + private val release by project.tasks.creating { group = KScienceProjectPlugin.RELEASE_GROUP description = "Publish development or production release based on version suffix" } @@ -90,7 +90,7 @@ public class KSciencePublishingExtension(public val project: Project) { try { project.addGithubPublishing(githubOrg, githubProject) linkPublicationsToReleaseTask("github") - } catch (t: Throwable){ + } catch (t: Throwable) { project.logger.error("Failed to set up github publication", t) } } @@ -170,7 +170,7 @@ public open class KScienceProjectPlugin : Plugin { if (readmeExtension.readmeTemplate.exists()) { inputs.file(readmeExtension.readmeTemplate) } - readmeExtension.additionalFiles.forEach { + readmeExtension.inputFiles.forEach { if (it.exists()) { inputs.file(it) } @@ -205,7 +205,8 @@ public open class KScienceProjectPlugin : Plugin { if (rootReadmeExtension.readmeTemplate.exists()) { inputs.file(rootReadmeExtension.readmeTemplate) } - rootReadmeExtension.additionalFiles.forEach { + + rootReadmeExtension.inputFiles.forEach { if (it.exists()) { inputs.file(it) } @@ -242,13 +243,11 @@ public open class KScienceProjectPlugin : Plugin { appendLine("
") } - val rootReadmeProperties: Map = - rootReadmeExtension.actualizedProperties + ("modules" to modulesString) + rootReadmeExtension.property("modules", modulesString) - readmeFile.writeText( - SimpleTemplateEngine().createTemplate(rootReadmeExtension.readmeTemplate) - .make(rootReadmeProperties).toString() - ) + rootReadmeExtension.readmeString()?.let { + readmeFile.writeText(it) + } } } diff --git a/src/main/kotlin/ru/mipt/npm/gradle/KScienceReadmeExtension.kt b/src/main/kotlin/ru/mipt/npm/gradle/KScienceReadmeExtension.kt index 9d2b283..1ba3785 100644 --- a/src/main/kotlin/ru/mipt/npm/gradle/KScienceReadmeExtension.kt +++ b/src/main/kotlin/ru/mipt/npm/gradle/KScienceReadmeExtension.kt @@ -1,6 +1,9 @@ package ru.mipt.npm.gradle -import groovy.text.SimpleTemplateEngine +import freemarker.cache.StringTemplateLoader +import freemarker.template.Configuration +import freemarker.template.Template +import freemarker.template.TemplateNotFoundException import kotlinx.html.TagConsumer import kotlinx.html.div import kotlinx.html.stream.createHTML @@ -8,6 +11,7 @@ import kotlinx.validation.ApiValidationExtension import org.gradle.api.Project import org.gradle.kotlin.dsl.findByType import java.io.File +import java.io.StringWriter import kotlin.collections.component1 import kotlin.collections.component2 import kotlin.collections.set @@ -20,6 +24,12 @@ public enum class Maturity { DEPRECATED } +private fun Template.processToString(args: Map): String { + val writer = StringWriter() + process(args, writer) + return writer.toString() +} + public class KScienceReadmeExtension(public val project: Project) { public var description: String = project.description ?: "" @@ -40,7 +50,41 @@ public class KScienceReadmeExtension(public val project: Project) { } } + /** + * If true, use default templates provided by plugin if override is not defined + */ + public var useDefaultReadmeTemplate: Boolean = true + + /** + * Use this template file if it is provided, otherwise use default template + */ public var readmeTemplate: File = project.file("docs/README-TEMPLATE.md") + set(value) { + field = value + if (value.exists()) { + fmLoader.putTemplate("readme", value.readText()) + } + } + + private val fmLoader = StringTemplateLoader().apply { + putTemplate( + "artifact", + this@KScienceReadmeExtension.javaClass.getResource("/templates/ARTIFACT-TEMPLATE.md")!!.readText() + ) + if (readmeTemplate.exists()) { + putTemplate("readme", readmeTemplate.readText()) + } else if (useDefaultReadmeTemplate) { + putTemplate( + "readme", + this@KScienceReadmeExtension.javaClass.getResource("/templates/README-TEMPLATE.md")!!.readText() + ) + } + } + + private val fmCfg = Configuration(Configuration.VERSION_2_3_31).apply { + defaultEncoding = "UTF-8" + templateLoader = fmLoader + } public data class Feature(val id: String, val description: String, val ref: String?, val name: String = id) @@ -73,11 +117,20 @@ public class KScienceReadmeExtension(public val project: Project) { "name" to { project.name }, "group" to { project.group }, "version" to { project.version }, - "features" to { featuresString() } + "description" to { project.description ?: "" }, + "features" to { featuresString() }, + "published" to { project.plugins.findPlugin("maven-publish") != null }, + "artifact" to { + val projectProperties = mapOf( + "name" to project.name, + "group" to project.group, + "version" to project.version + ) + fmCfg.getTemplate("artifact").processToString(projectProperties) + } ) - public val actualizedProperties: Map - get() = properties.mapValues { (_, value) -> value() } + public fun getPropertyValues(): Map = properties.mapValues { (_, value) -> value() } public fun property(key: String, value: Any?) { properties[key] = { value } @@ -87,17 +140,28 @@ public class KScienceReadmeExtension(public val project: Project) { properties[key] = value } - public fun propertyByTemplate(key: String, template: String) { - val actual = actualizedProperties - properties[key] = { SimpleTemplateEngine().createTemplate(template).make(actual).toString() } + public fun propertyByTemplate(key: String, templateString: String) { + //need to freeze it, otherwise values could change + val actual = getPropertyValues() + fmLoader.putTemplate(key, templateString) + val template = fmCfg.getTemplate(key) + + properties[key] = { template.processToString(actual) } } - internal val additionalFiles = ArrayList() + /** + * Files that are use in readme generation + */ + internal val inputFiles = ArrayList() - public fun propertyByTemplate(key: String, template: File) { - val actual = actualizedProperties - properties[key] = { SimpleTemplateEngine().createTemplate(template).make(actual).toString() } - additionalFiles += template + public fun propertyByTemplate(key: String, templateFile: File) { + //need to freeze it, otherwise values could change + val actual = getPropertyValues() + fmLoader.putTemplate(key, templateFile.readText()) + val template: Template = fmCfg.getTemplate(key) + + properties[key] = { template.processToString(actual) } + inputFiles += templateFile } /** @@ -110,12 +174,12 @@ public class KScienceReadmeExtension(public val project: Project) { } /** - * Generate a readme string from the stub + * Generate a readme string from the template */ - public fun readmeString(): String? = if (readmeTemplate.exists()) { - val actual = actualizedProperties - SimpleTemplateEngine().createTemplate(readmeTemplate).make(actual).toString() - } else { + public fun readmeString(): String? = try { + fmCfg.getTemplate("readme").processToString(getPropertyValues()) + } catch (ex: TemplateNotFoundException) { + project.logger.warn("Template with name ${ex.templateName} not found in ${project.name}") null } } diff --git a/src/main/resources/templates/ARTIFACT-TEMPLATE.md b/src/main/resources/templates/ARTIFACT-TEMPLATE.md new file mode 100644 index 0000000..4f04b4d --- /dev/null +++ b/src/main/resources/templates/ARTIFACT-TEMPLATE.md @@ -0,0 +1,26 @@ +## Artifact: + +The Maven coordinates of this project are `${group}:${name}:${version}`. + +**Gradle Groovy:** +```groovy +repositories { + maven { url 'https://repo.kotlin.link' } + mavenCentral() +} + +dependencies { + implementation '${group}:${name}:${version}' +} +``` +**Gradle Kotlin DSL:** +```kotlin +repositories { + maven("https://repo.kotlin.link") + mavenCentral() +} + +dependencies { + implementation("${group}:${name}:${version}") +} +``` \ No newline at end of file diff --git a/src/main/resources/templates/README-TEMPLATE.md b/src/main/resources/templates/README-TEMPLATE.md new file mode 100644 index 0000000..63e6d31 --- /dev/null +++ b/src/main/resources/templates/README-TEMPLATE.md @@ -0,0 +1,15 @@ +# Module ${name} + +${description} + +<#if features?has_content> +## Features + +${features} + + +<#if published> +## Usage + +${artifact} +