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
 

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<MavenPublication>("catalog") {
                 from(components["versionCatalog"])
-                this.artifactId = "version-catalog"
+                artifactId = "version-catalog"
 
                 pom {
                     name.set("version-catalog")

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"

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<Project> {
     override fun apply(project: Project): Unit = project.configureKScience(
-        KotlinVersion(1, 6, 0)
+        KotlinVersion(1, 6, 10)
     )
 }

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<Project> {
                 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<Project> {
             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<Project> {
                         appendLine("<hr/>")
                     }
 
-                    val rootReadmeProperties: Map<String, Any?> =
+                    rootReadmeExtension.property("modules", modulesString)
-                        rootReadmeExtension.actualizedProperties + ("modules" to modulesString)
 
-                    readmeFile.writeText(
+                    rootReadmeExtension.readmeString()?.let {
-                        SimpleTemplateEngine().createTemplate(rootReadmeExtension.readmeTemplate)
+                        readmeFile.writeText(it)
-                            .make(rootReadmeProperties).toString()
+                    }
-                    )
                 }
 
             }

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, Any?>): 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<String, Any?>
+    public fun getPropertyValues(): Map<String, Any?> = properties.mapValues { (_, value) -> value() }
-        get() = 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) {
+    public fun propertyByTemplate(key: String, templateString: String) {
-        val actual = actualizedProperties
+        //need to freeze it, otherwise values could change
-        properties[key] = { SimpleTemplateEngine().createTemplate(template).make(actual).toString() }
+        val actual = getPropertyValues()
+        fmLoader.putTemplate(key, templateString)
+        val template = fmCfg.getTemplate(key)
+
+        properties[key] = { template.processToString(actual) }
     }
 
-    internal val additionalFiles = ArrayList<File>()
+    /**
+     * Files that are use in readme generation
+     */
+    internal val inputFiles = ArrayList<File>()
 
-    public fun propertyByTemplate(key: String, template: File) {
+    public fun propertyByTemplate(key: String, templateFile: File) {
-        val actual = actualizedProperties
+        //need to freeze it, otherwise values could change
-        properties[key] = { SimpleTemplateEngine().createTemplate(template).make(actual).toString() }
+        val actual = getPropertyValues()
-        additionalFiles += template
+        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()) {
+    public fun readmeString(): String? = try {
-        val actual = actualizedProperties
+        fmCfg.getTemplate("readme").processToString(getPropertyValues())
-        SimpleTemplateEngine().createTemplate(readmeTemplate).make(actual).toString()
+    } catch (ex: TemplateNotFoundException) {
-    } else {
+        project.logger.warn("Template with name ${ex.templateName} not found in ${project.name}")
         null
     }
 }

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}")
+}
+```

src/main/resources/templates/README-TEMPLATE.md

@@ -0,0 +1,15 @@
+# Module ${name}
+
+${description}
+
+<#if features?has_content>
+## Features
+
+${features}
+
+</#if>
+<#if published>
+## Usage
+
+${artifact}
+</#if>