Composite Build (#15)

build-logic/build.gradle.kts

@@ -10,4 +10,5 @@ dependencies {
     implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0")
     implementation("com.palantir.gradle.gitversion:gradle-git-version:0.15.0")
     implementation("com.gradle.publish:plugin-publish-plugin:1.1.0")
-}
+    implementation("com.github.gmazzo:gradle-buildconfig-plugin:3.1.0")
+}

build-logic/src/main/kotlin/publish-plugin.gradle.kts

@@ -5,6 +5,12 @@ plugins {
 
     id("java-gradle-plugin")
     id("com.gradle.plugin-publish")
+
+    id("com.github.gmazzo.buildconfig")
+}
+
+buildConfig {
+    buildConfigField("String", "VERSION", "\"${project.version}\"")
 }
 
 java {
@@ -17,6 +23,19 @@ tasks.withType<KotlinCompile>().configureEach {
     }
 }
 
+tasks.getByName("publishPlugins") {
+    doFirst {
+        val version = "${project.version}"
+
+        val isValid = !version.endsWith(".dirty")
+            && version.count { it == '-' } < 2
+
+        check(isValid) {
+            "project.version ${project.version} does not appear to be a valid release version"
+        }
+    }
+}
+
 repositories {
     gradlePluginPortal()
 }

docusaurus/docs/intro.md

@@ -35,3 +35,33 @@ Markout is designed to integrate with [Kapshot](https://github.com/mfwgenerics/k
 a minimal Kotlin compiler plugin that allows source code to be
 captured and inspected at runtime.
 Kapshot is the magic ingredient that enables fully executable and testable sample code blocks.
+
+## How it works
+
+Markout generates files by running code in a Kotlin project with the Markout Gradle plugin applied.
+You supply a `main` method which invokes a `markout` block to describe how files should be generated.
+This code runs every time files are generated or checked.
+
+```kotlin title="Main.kt"
+fun main() = markout {
+    file("README.txt", "Hello world!")
+
+    directory("docs") {
+        file("INTRO.txt", "Another text file!")
+        file("OUTRO.txt", "A final text file")
+    }
+}
+```
+
+When the code above is run using `:markout`, it generates the following files
+and merges them into the project directory.
+
+```
+my-project
+├─ README.txt
+└─ docs
+   ├─ INTRO.txt
+   └─ OUTRO.txt
+```
+
+The `:markoutCheck` task then verifies that these files match subsequent reruns of the code.

docusaurus/docusaurus.config.js

@@ -54,6 +54,7 @@ themeConfig:
     prism: {
       theme: lightCodeTheme,
       darkTheme: darkCodeTheme,
+      additionalLanguages: ["kotlin", "java"],
     },
   }),
 };

markout-docusaurus-plugin/build.gradle.kts

@@ -4,6 +4,8 @@ plugins {
 
 dependencies {
     implementation("com.github.node-gradle:gradle-node-plugin:3.5.1")
+    implementation("io.koalaql:kapshot-plugin-gradle:0.1.1")
+    implementation("io.koalaql:markout-plugin")
 }
 
 pluginBundle {
@@ -15,7 +17,7 @@ pluginBundle {
 gradlePlugin {
     plugins {
         create("markoutPlugin") {
-            id = "io.koalaql.markout"
+            id = "io.koalaql.markout-docusaurus"
             displayName = "Markout Docusaurus Plugin"
             description = "Plugin Support for Markout Powered Docusaurus Sites"
             implementationClass = "io.koalaql.markout.docusaurus.GradlePlugin"

markout-docusaurus-plugin/src/main/kotlin/io/koalaql/markout/docusaurus/GradlePlugin.kt

@@ -10,6 +10,7 @@ import org.gradle.api.Plugin
 import org.gradle.api.Project
 
 import com.github.gradle.node.yarn.task.YarnTask
+import io.koalaql.markout_plugin.BuildConfig
 import org.gradle.api.Action
 import org.gradle.api.DefaultTask
 import org.gradle.api.model.ObjectFactory
@@ -186,7 +187,14 @@ abstract class RunDocusaurus: DefaultTask() {
 
 class GradlePlugin: Plugin<Project> {
     override fun apply(target: Project) = with (target) {
-        plugins.apply("com.github.node-gradle.node")
+        dependencies.add("api", "io.koalaql:markout-markdown:${BuildConfig.VERSION}")
+        dependencies.add("api", "io.koalaql:markout-docusaurus:${BuildConfig.VERSION}")
+
+        with(plugins) {
+            apply("com.github.node-gradle.node")
+            apply("io.koalaql.markout")
+            apply("io.koalaql.kapshot-plugin")
+        }
 
         extensions.configure(NodeExtension::class.java) {
             it.download.set(true)

markout-docusaurus/build.gradle.kts

@@ -9,7 +9,7 @@ plugins {
 dependencies {
     api(kotlin("reflect"))
 
-    api(project(":markout-markdown"))
+    api("io.koalaql:markout-markdown")
 
     testImplementation(kotlin("test"))
 }

markout-docusaurus/src/main/kotlin/io/koalaql/markout/docusaurus/DocusaurusSettings.kt

@@ -195,6 +195,7 @@ fun buildConfigJs(out: LineWriter, builder: DocusaurusSettings.() -> Unit) {
         prism: {
           theme: lightCodeTheme,
           darkTheme: darkCodeTheme,
+          additionalLanguages: ["kotlin", "java"],
         },
       }),
     };

markout-docusaurus/testing/docusaurus.config.js

@@ -60,6 +60,7 @@ themeConfig:
     prism: {
       theme: lightCodeTheme,
       darkTheme: darkCodeTheme,
+      additionalLanguages: ["kotlin", "java"],
     },
   }),
 };

markout-github-workflows-kt/build.gradle.kts

@@ -9,7 +9,7 @@ plugins {
 dependencies {
     api(kotlin("reflect"))
 
-    api(project(":markout"))
+    api("io.koalaql:markout")
 
     api("it.krzeminski:github-actions-kotlin-dsl:0.36.0")
 

markout-markdown/build.gradle.kts

@@ -9,7 +9,7 @@ plugins {
 dependencies {
     api(kotlin("reflect"))
 
-    api(project(":markout"))
+    api("io.koalaql:markout")
 
     testImplementation(kotlin("test"))
 }

markout-plugin/build.gradle.kts

@@ -11,7 +11,7 @@ pluginBundle {
 gradlePlugin {
     plugins {
         create("markoutPlugin") {
-            id = "io.koalaql.markout-docusaurus"
+            id = "io.koalaql.markout"
             displayName = "Markout Plugin"
             description = "Plugin Support for Markout: an executable documentation platform and Markdown DSL for Kotlin"
             implementationClass = "io.koalaql.markout.GradlePlugin"

markout-plugin/src/main/kotlin/io/koalaql/markout/GradlePlugin.kt

@@ -6,9 +6,12 @@ import org.gradle.api.Project
 import org.gradle.api.plugins.JavaPluginExtension
 import org.gradle.api.tasks.JavaExec
 import java.util.concurrent.Callable
+import io.koalaql.markout_plugin.BuildConfig
 
 class GradlePlugin: Plugin<Project> {
     override fun apply(target: Project) = with(target) {
+        dependencies.add("api", "io.koalaql:markout:${BuildConfig.VERSION}")
+
         target.extensions.create("markout", MarkoutConfig::class.java)
 
         val configureTask = tasks.register("markoutConfigure", DefaultTask::class.java) {

readme/build.gradle.kts

@@ -5,21 +5,15 @@ repositories {
 plugins {
     id("conventions")
 
-    id("io.koalaql.markout")
     id("io.koalaql.markout-docusaurus")
-
-    id("io.koalaql.kapshot-plugin") version "0.1.1"
 }
 
 markout {
     mainClass = "MainKt"
 }
 
 dependencies {
-    implementation(project(":markout"))
-    implementation(project(":markout-markdown"))
-    implementation(project(":markout-docusaurus"))
-    implementation(project(":markout-github-workflows-kt"))
+    implementation("io.koalaql:markout-github-workflows-kt")
 
     implementation(kotlin("reflect"))
-}
+}

readme/src/main/kotlin/Constants.kt

@@ -0,0 +1 @@
+const val MARKOUT_VERSION: String = "0.0.7"

readme/src/main/kotlin/Util.kt

@@ -78,13 +78,16 @@ private val PIPES_PREFIX = Prefix(
 private fun drawFileTree(
     prefix: Prefix,
     output: Output,
-    writer: LineWriter
+    writer: LineWriter,
+    dotfiles: Boolean = true
 ) {
     when (output) {
         is OutputDirectory -> {
-            val entries = (mapOf(".markout" to OutputEntry(false, OutputFile { })) + output.entries())
-                .entries
-                .toList()
+            val entries = if (dotfiles) {
+                (mapOf(".markout" to OutputEntry(false, OutputFile { })) + output.entries())
+            } else {
+                output.entries()
+            }.toList()
 
             entries.forEachIndexed { ix, (key, entry) ->
                 val p = if (ix < entries.size - 1) prefix.pre else prefix.post
@@ -93,12 +96,12 @@ private fun drawFileTree(
                 writer.inline(key)
                 writer.newline()
 
-                drawFileTree(PIPES_PREFIX, entry.output, writer.prefixed(p.indent))
+                drawFileTree(PIPES_PREFIX, entry.output, writer.prefixed(p.indent), dotfiles)
             }
         }
         is OutputFile -> { }
     }
 }
 
-fun drawFileTree(output: Output): String =
-    "${StringBuilder().also { drawFileTree(NO_PREFIX, output, AppendableLineWriter(it).trimmedLines()) }}"
+fun drawFileTree(output: Output, dotfiles: Boolean = true): String =
+    "${StringBuilder().also { drawFileTree(NO_PREFIX, output, AppendableLineWriter(it).trimmedLines(), dotfiles) }}"

readme/src/main/kotlin/docusaurus/Docusaurus.kt

@@ -1,7 +1,13 @@
 package docusaurus
 
+import drawFileTree
+import io.koalaql.kapshot.CapturedBlock
 import io.koalaql.markout.Markout
+import io.koalaql.markout.buildOutput
 import io.koalaql.markout.docusaurus.docusaurus
+import io.koalaql.markout.md.markdown
+import io.koalaql.markout.output.OutputDirectory
+import io.koalaql.markout.output.OutputEntry
 
 fun Markout.setupDocusaurus() = docusaurus {
     configure {
@@ -63,6 +69,44 @@ fun Markout.setupDocusaurus() = docusaurus {
                 -"captured and inspected at runtime."
                 -"Kapshot is the magic ingredient that enables fully executable and testable sample code blocks."
             }
+
+            h2("How it works")
+
+            -"Markout generates files by running code in a Kotlin project with the Markout Gradle plugin applied."
+            -"You supply a `main` method which invokes a `markout` block to describe how files should be generated."
+            -"This code runs every time files are generated or checked."
+
+            var fileTree: String = ""
+
+            fun markout(builder: Markout.() -> Unit) {
+                fileTree = drawFileTree(object : OutputDirectory {
+                    override fun entries(): Map<String, OutputEntry> = mapOf("my-project" to OutputEntry(
+                        tracked = false,
+                        buildOutput(builder)
+                    ))
+                }, dotfiles = false)
+            }
+
+            fun execBlock(block: CapturedBlock<Unit>): String =
+                block.source.text.also { block.invoke() }
+
+            code("kotlin", "Main.kt", "fun main() = ${execBlock {
+                markout {
+                    file("README.txt", "Hello world!")
+
+                    directory("docs") {
+                        file("INTRO.txt", "Another text file!")
+                        file("OUTRO.txt", "A final text file")
+                    }
+                }
+            }}")
+
+            -"When the code above is run using `:markout`, it generates the following files"
+            -"and merges them into the project directory."
+
+            code(fileTree)
+
+            -"The `:markoutCheck` task then verifies that these files match subsequent reruns of the code."
         }
     }
 }

settings.gradle.kts

@@ -1,12 +1,8 @@
-pluginManagement {
-    includeBuild("build-logic")
-}
-
+includeBuild("build-logic")
 includeBuild("markout-plugin")
 includeBuild("markout-docusaurus-plugin")
-
-include("markout")
-include("markout-markdown")
-include("markout-docusaurus")
-include("markout-github-workflows-kt")
+includeBuild("markout")
+includeBuild("markout-markdown")
+includeBuild("markout-docusaurus")
+includeBuild("markout-github-workflows-kt")
 include("readme")