support snippet outputs with korro

Author: koperagen

core/build.gradle.kts

@@ -1,5 +1,6 @@
 import com.google.devtools.ksp.gradle.KspTaskJvm
 import com.google.devtools.ksp.gradle.KspTask
+import io.github.devcrocod.korro.KorroTask
 import nl.jolanrensen.docProcessor.defaultProcessors.*
 import nl.jolanrensen.docProcessor.gradle.creatingProcessDocTask
 import org.gradle.jvm.tasks.Jar
@@ -103,6 +104,7 @@ val samplesTest = tasks.register<Test>("samplesTest") {
     doFirst {
         delete {
             delete(fileTree(File(buildDir, "dataframes")))
+            delete(fileTree(File(buildDir, "korroOutputLines")))
         }
     }
 
@@ -137,6 +139,10 @@ val copySamplesOutputs = tasks.register<JavaExec>("copySamplesOutputs") {
     classpath = sourceSets.test.get().runtimeClasspath
 }
 
+tasks.withType<KorroTask> {
+    dependsOn(copySamplesOutputs)
+}
+
 val generatedSourcesFolderName = "generated-sources"
 val addGeneratedSourcesToGit by tasks.creating(GitTask::class) {
     directory.set(file("."))
@@ -217,6 +223,10 @@ korro {
         include("src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/*.kt")
     }
 
+    outputs = fileTree(project.buildDir) {
+        include("korroOutputLines/*")
+    }
+
     groupSamples {
 
         beforeSample.set("<tab title=\"NAME\">\n")

core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/explainer/PluginCallbackProxy.kt

@@ -130,6 +130,17 @@ object PluginCallbackProxy : PluginCallback {
             it.mkdirs()
         }
         output.writeHTML(File(destination, "$name.html"))
+        val korro = File("build/korroOutputLines").also {
+            it.mkdirs()
+        }
+
+        val group = name.substringBefore("_")
+        File(korro, group).writeText(
+            """
+            
+            <dataFrame src="$group.html"/>
+            """.trimIndent()
+        )
     }
 
     private fun statementOutput(

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/explainer/PluginCallbackProxy.kt

@@ -130,6 +130,17 @@ object PluginCallbackProxy : PluginCallback {
             it.mkdirs()
         }
         output.writeHTML(File(destination, "$name.html"))
+        val korro = File("build/korroOutputLines").also {
+            it.mkdirs()
+        }
+
+        val group = name.substringBefore("_")
+        File(korro, group).writeText(
+            """
+            
+            <dataFrame src="$group.html"/>
+            """.trimIndent()
+        )
     }
 
     private fun statementOutput(

docs/StardustDocs/topics/ColumnSelectors.md

@@ -57,39 +57,6 @@ df.select { name.all() }
 df.select { name.allDfs() }
 ```
 
-</tab>
-<tab title="Strings">
-
-```kotlin
-// by column name
-df.select { it["name"] }
-
-// by column path
-df.select { it["name"]["firstName"] }
-df.select { "name"["firstName"] }
-
-// with a new name
-df.select { "name" named "Full Name" }
-
-// converted
-df.select { "name"["firstName"]<String>().map { it.uppercase() } }
-
-// column arithmetics
-df.select { 2021 - "age"<Int>() }
-
-// two columns
-df.select { "name" and "age" }
-
-// by range of names
-df.select { "name".."age" }
-
-// all children of ColumnGroup
-df.select { "name".all() }
-
-// depth-first-search traversal of all children columns
-df.select { "name".allDfs() }
-```
-
 </tab>
 <tab title="Accessors">
 
@@ -127,42 +94,39 @@ df.select { name.allDfs() }
 ```
 
 </tab>
-<tab title="KProperties">
+<tab title="Strings">
 
 ```kotlin
 // by column name
-df.select { it[Person::name] }
-df.select { (Person::name)() }
-df.select { col(Person::name) }
+df.select { it["name"] }
 
 // by column path
-df.select { it[Person::name][Name::firstName] }
-df.select { Person::name[Name::firstName] }
+df.select { it["name"]["firstName"] }
+df.select { "name"["firstName"] }
 
 // with a new name
-df.select { Person::name named "Full Name" }
+df.select { "name" named "Full Name" }
 
 // converted
-df.select { Person::name[Name::firstName].map { it.lowercase() } }
+df.select { "name"["firstName"]<String>().map { it.uppercase() } }
 
 // column arithmetics
-df.select { 2021 - (Person::age)() }
+df.select { 2021 - "age"<Int>() }
 
 // two columns
-df.select { Person::name and Person::age }
+df.select { "name" and "age" }
 
-// range of columns
-df.select { Person::name..Person::age }
+// by range of names
+df.select { "name".."age" }
 
 // all children of ColumnGroup
-df.select { Person::name.all() }
+df.select { "name".all() }
 
 // depth-first-search traversal of all children columns
-df.select { Person::name.allDfs() }
+df.select { "name".allDfs() }
 ```
 
-</tab>
-</tabs>
+</tab></tabs>
 <dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.Access.columnSelectors.html"/>
 <!---END-->
 

docs/StardustDocs/topics/DataColumn.md

@@ -62,7 +62,6 @@ df.add("year of birth") { 2021 - age }
 df.filter { age > 30 }
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.Create.columnAccessorsUsage.html"/>
 <!---END-->
 
 [Column accessors](DataColumn.md#column-accessors) are created by [property delegate](https://kotlinlang.org/docs/delegated-properties.html) `column`. Column [`type`](DataColumn.md#properties) should be passed as type argument, column [`name`](DataColumn.md#properties) will be taken from the variable name.
@@ -73,7 +72,6 @@ df.filter { age > 30 }
 val name by column<String>()
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.Create.createColumnAccessor.html"/>
 <!---END-->
 
 To assign column name explicitly, pass it as an argument.
@@ -84,7 +82,6 @@ To assign column name explicitly, pass it as an argument.
 val accessor by column<String>("complex column name")
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.Create.createColumnAccessorRenamed.html"/>
 <!---END-->
 
 You can also create column accessors for [ColumnGroups](DataColumn.md#columngroup) and [FrameColumns](DataColumn.md#framecolumn)
@@ -96,7 +93,6 @@ val columns by columnGroup()
 val frames by frameColumn()
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.Create.createGroupOrFrameColumnAccessor.html"/>
 <!---END-->
 
 To reference nested columns inside [ColumnGroups](DataColumn.md#columngroup), invoke `column<T>()` on accessor to parent [`ColumnGroup`](#columngroup):
@@ -108,7 +104,6 @@ val name by columnGroup()
 val firstName by name.column<String>()
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.Create.createDeepColumnAccessor.html"/>
 <!---END-->
 
 You can also create virtual accessor that doesn't point to a real column but computes some expression on every data access:
@@ -146,7 +141,6 @@ df[fullName]
 ```
 
 </tab></tabs>
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.Create.columnAccessorComputed.html"/>
 <!---END-->
 
 If expression depends only on one column, you can also use `map`:
@@ -173,6 +167,5 @@ val ageCol1 = age.withValues(15, 20)
 val ageCol2 = age.withValues(1..10)
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.Create.columnAccessorToColumn.html"/>
 <!---END-->
 

docs/StardustDocs/topics/KPropertiesApi.md

@@ -28,7 +28,6 @@ val passengers = DataFrame.read("titanic.csv")
     .toListOf<Passenger>()
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.ApiLevels.kproperties1.html"/>
 <!---END-->
 
 By default, [`DataFrame`](DataFrame.md) uses `name` and `returnType` of `KProperty` for typed access to data. 
@@ -48,5 +47,4 @@ val passengers = DataFrame.read("titanic.csv")
     .toListOf<Passenger>()
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.ApiLevels.kproperties2.html"/>
 <!---END-->

docs/StardustDocs/topics/access.md

@@ -13,7 +13,6 @@ df.rows() // Iterable<DataRow>
 df.values() // Sequence<Any?>
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.Access.getRowsColumns.html"/>
 <!---END-->
 
 **Learn how to:**

docs/StardustDocs/topics/add.md

@@ -142,12 +142,12 @@ Consider this API:
 
 ```kotlin
 class CityInfo(val city: String?, val population: Int, val location: String)
+
 fun queryCityInfo(city: String?): CityInfo {
     return CityInfo(city, city?.length ?: 0, "35.5 32.2")
 }
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.Modify.addCalculatedApi.html"/>
 <!---END-->
 
 Use the following approach to add multiple columns by calling the given API only once per row:
@@ -194,7 +194,6 @@ val personWithCityInfo = df.add {
 ```
 
 </tab></tabs>
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.Modify.addCalculated.html"/>
 <!---END-->
 
 ## Add existing column to [`DataFrame`](DataFrame.md)

docs/StardustDocs/topics/apiLevels.md

@@ -52,7 +52,6 @@ DataFrame.read("titanic.csv")
     }
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.ApiLevels.strings.html"/>
 <!---END-->
 
 </tab>
@@ -74,7 +73,6 @@ DataFrame.read("titanic.csv")
     .filter { survived() && home().endsWith("NY") && age()!! in 10..20 }
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.ApiLevels.accessors3.html"/>
 <!---END-->
 
 </tab>
@@ -102,7 +100,6 @@ val passengers = DataFrame.read("titanic.csv")
     .toListOf<Passenger>()
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.ApiLevels.kproperties1.html"/>
 <!---END-->
 
 </tab>
@@ -115,7 +112,6 @@ val passengers = DataFrame.read("titanic.csv")
 val df = DataFrame.read("titanic.csv")
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.ApiLevels.extensionProperties1.html"/>
 <!---END-->
 
 <!---FUN extensionProperties2-->
@@ -126,7 +122,6 @@ df.add("lastName") { name.split(",").last() }
     .filter { survived && home.endsWith("NY") && age in 10..20 }
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.ApiLevels.extensionProperties2.html"/>
 <!---END-->
 
 </tab>

docs/StardustDocs/topics/collectionsInterop.md

@@ -26,7 +26,6 @@ df.rows() // Iterable<DataRow>
 df.values() // Sequence<Any?>
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.Access.getRowsColumns.html"/>
 <!---END-->
 
 ## Interop with data classes
@@ -43,7 +42,6 @@ data class Input(val a: Int, val b: Int)
 val list = listOf(Input(1, 2), Input(3, 4))
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.Collections.listInterop1.html"/>
 <!---END-->
 
 You can convert this list into [`DataFrame`](DataFrame.md) using [`toDataFrame()`](createDataFrame.md#todataframe) extension:
@@ -54,7 +52,6 @@ You can convert this list into [`DataFrame`](DataFrame.md) using [`toDataFrame()
 val df = list.toDataFrame()
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.Collections.listInterop2.html"/>
 <!---END-->
 
 Mark original data class with [`DataSchema`](schemas.md) annotation to get [extension properties](extensionPropertiesApi.md) and perform data transformations.
@@ -68,7 +65,6 @@ data class Input(val a: Int, val b: Int)
 val df2 = df.add("c") { a + b }
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.Collections.listInterop3.html"/>
 <!---END-->
 
 <tip>
@@ -89,7 +85,6 @@ data class Output(val a: Int, val b: Int, val c: Int)
 val result = df2.toListOf<Output>()
 ```
 
-<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.Collections.listInterop4.html"/>
 <!---END-->
 
 ### Converting columns with objects instances to ColumnGroup