Add initial compiler plugin documentation

Author: koperagen

data/participants.json

@@ -0,0 +1,44 @@
+[
+  {
+    "id": "1",
+    "participants": [
+      {
+        "name": {
+          "firstName": "Alice",
+          "lastName": "Cooper"
+        },
+        "age": 15,
+        "city": "London"
+      },
+      {
+        "name": {
+          "firstName": "Bob",
+          "lastName": "Dylan"
+        },
+        "age": 45,
+        "city": "Dubai"
+      }
+    ]
+  },
+  {
+    "id": "2",
+    "participants": [
+      {
+        "name": {
+          "firstName": "Charlie",
+          "lastName": "Daniels"
+        },
+        "age": 20,
+        "city": "Moscow"
+      },
+      {
+        "name": {
+          "firstName": "Charlie",
+          "lastName": "Chaplin"
+        },
+        "age": 40,
+        "city": "Milan"
+      }
+    ]
+  }
+]

docs/StardustDocs/d.tree

@@ -43,6 +43,9 @@
         <toc-element topic="DataColumn.md"/>
         <toc-element topic="DataRow.md"/>
     </toc-element>
+    <toc-element topic="Compiler-Plugin.md">
+        <toc-element topic="dataSchema.md"/>
+    </toc-element>
     <toc-element topic="nanAndNa.md"/>
     <toc-element topic="numberUnification.md"/>
     <toc-element topic="operations.md">
@@ -195,7 +198,6 @@
         </toc-element>
     </toc-element>
     <toc-element topic="gradleReference.md"/>
-    <toc-element topic="Compiler-Plugin.md"/>
     <toc-element topic="DataSchema-Data-Classes-Generation.md"/>
     <toc-element topic="_shadow_resources.md" hidden="true"/>
 </instance-profile>

docs/StardustDocs/images/compiler_plugin.mp4

@@ -1,3 +1,111 @@
 # Kotlin DataFrame Compiler Plugin
 
-TODO
+Kotlin DataFrame compiler plugin: available in Gradle projects, is coming to Kotlin Notebook and Maven projects soon.
+
+Check out this video that shows how expressions update the schema of a dataframe: 
+<video src="compiler_plugin.mp4" controls/>
+
+## Setup
+
+Install [IntelliJ IDEA EAP](https://www.jetbrains.com/idea/nextversion/). 
+Going forward, compiler plugin updates will be released with Kotlin plugin updates. 
+Next release: 2025.2
+
+Setup plugins in `build.gradle.kts`:
+
+```kotlin
+kotlin("jvm") version "2.2.20-dev-3524"
+```
+
+```kotlin
+kotlin("plugin.dataframe") version "2.2.20-dev-3524"
+```
+
+Setup library dependency:
+```kotlin
+implementation("org.jetbrains.kotlinx:dataframe:1.0.0-Beta2")
+```
+
+Plugin is released as a dev version, available in this maven repository:
+
+```kotlin
+maven("https://packages.jetbrains.team/maven/p/kt/dev/")
+```
+
+Setup repositories for dependencies in `build.gradle.kts`:
+```kotlin
+repositories {
+    maven("https://packages.jetbrains.team/maven/p/kt/dev/")
+    mavenCentral()
+}
+```
+
+Setup repositories for plugins in `settings.gradle.kts`
+```kotlin
+pluginManagement {
+    repositories {
+        maven("https://packages.jetbrains.team/maven/p/kt/dev/")
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+```
+
+Add this line to `gradle.properties`: 
+```properties
+kotlin.incremental=false
+```
+
+Disabling incremental compilation will no longer be necessary
+when https://youtrack.jetbrains.com/issue/KT-66735 is resolved.
+
+## Features overview
+
+### Static interpretation of DataFrame API
+
+Plugin evaluates dataframe operations, given compile-time known arguments such as constant String, resolved types, property access calls.
+It updates the return type of the function call to provide properties that match column names and types.
+The goal is to reflect the result of operations you apply to dataframe in types and have convenient typed API 
+
+```kotlin
+val weatherData = dataFrameOf(
+    "time" to columnOf(0, 1, 2, 4, 5, 7, 8, 9),
+    "temperature" to columnOf(12.0, 14.2, 15.1, 15.9, 17.9, 15.6, 14.2, 24.3),
+    "humidity" to columnOf(0.5, 0.32, 0.11, 0.89, 0.68, 0.57, 0.56, 0.5)
+)
+
+weatherData.filter { temperature > 15.0 }.print()
+```
+
+The schema of DataFrame, as the compiler plugin sees it,
+is displayed when you hover on an expression or variable:
+
+![image.png](schema_info.png)
+
+### @DataSchema declarations
+
+Untyped DataFrame can be assigned a data schema - top-level interface or class that describes names and types of columns in the dataframe.
+
+```kotlin
+@DataSchema
+data class Repositories(
+    @ColumnName("full_name")
+    val fullName: String,
+    @ColumnName("html_url")
+    val htmlUrl: java.net.URL,
+    @ColumnName("stargazers_count")
+    val stargazersCount: Int,
+    val topics: String,
+    val watchers: Int
+)
+
+fun main() {
+    val df = DataFrame
+        .readCsv("https://raw.githubusercontent.com/Kotlin/dataframe/master/data/jetbrains_repositories.csv")
+        .convertTo<Repositories>()
+
+    df.filter { stargazersCount > 50 }.print()
+}
+```
+
+[Learn more](dataSchema.md) about data schema declarations

docs/StardustDocs/images/schema_info.png

@@ -0,0 +1,186 @@
+# @DataSchema declarations
+
+`DataSchema` can be used as an argument for cast and convertTo functions. 
+It provides typed data access for raw dataframes you read from I/O sources and serves as a starting point for the compiler plugin to derive schema changes.
+
+Example 1:
+```kotlin
+@DataSchema
+interface Person { 
+  val firstName: String
+}
+```
+
+Generated code:
+```kotlin
+val DataRow<Person>.firstName: Int = this["firstName"] as String
+val ColumnsScope<Person>.firstName: DataColumn<Int> = this["firstName"] as DataColumn<String>
+```
+
+Example 2:
+```kotlin
+@DataSchema
+interface Person {
+    @ColumnName("first_name")
+    val firstName: String
+}
+```
+
+`ColumnName` annotation changes how generated extension properties pull the data from a dataframe:
+
+Generated code:
+```kotlin
+val DataRow<Person>.firstName: Int = this["first_name"] as String
+val ColumnsScope<Person>.firstName: DataColumn<Int> = this["first_name"] as DataColumn<String>
+```
+
+Generated extension properties are used to access values in `DataRow` and to access columns in `ColumnsScope`, which is either `DataFrame` or `ColumnSelectionDsl` 
+
+`DataRow`:
+```kotlin
+val row = df[0]
+row.firstName
+```
+
+```kotlin
+df.filter { firstName.startsWith("L") }
+df.add("newCol") { firstName }
+```
+
+`DataFrame`:
+```kotlin
+val col = df.firstName
+val value = col[0]
+```
+
+`ColumnSelectionDsl`:
+
+```kotlin
+df.convert { firstName }.with { it.uppercase() }
+df.select { firstName }
+df.rename { firstName }.into("name")
+```
+
+## Data Class
+
+DataSchema can be a top-level data class, in which case two additional API become available
+
+```kotlin
+@DataSchema
+class WikiData(val name: String, val paradigms: List<String>)
+```
+
+1. `dataFrameOf` overload that creates a dataframe instance from objects
+
+```kotlin
+val languages = dataFrameOf(
+    WikiData("Kotlin", listOf("object-oriented", "functional", "imperative")), 
+    WikiData("Haskell", listOf("Purely functional")),
+    WikiData("C", listOf("imperative")),
+    WikiData("Pascal", listOf("imperative")),
+    WikiData("Idris", listOf("functional")),
+)
+```
+
+2. `append` overload that takes an object and appends it as a row
+
+```kotlin
+val ocaml = WikiData("OCaml", listOf("functional", "imperative", "modular", "object-oriented"))
+val languages1 = languages.append(ocaml)
+```
+
+## Schemas for nested structures
+
+Nested structure can be a JSON that you read from a file.
+
+```json
+[
+    {
+        "id": "1",
+        "participants": [
+            {
+                "name": {
+                    "firstName": "Alice",
+                    "lastName": "Cooper"
+                },
+                "age": 15,
+                "city": "London"
+            },
+            {
+                "name": {
+                    "firstName": "Bob",
+                    "lastName": "Dylan"
+                },
+                "age": 45,
+                "city": "Dubai"
+            }
+        ]
+    },
+    {
+        "id": "2",
+        "participants": [
+            {
+                "name": {
+                    "firstName": "Charlie",
+                    "lastName": "Daniels"
+                },
+                "age": 20,
+                "city": "Moscow"
+            },
+            {
+                "name": {
+                    "firstName": "Charlie",
+                    "lastName": "Chaplin"
+                },
+                "age": 40,
+                "city": "Milan"
+            }
+        ]
+    }
+]
+```
+
+You get dataframe with this schema
+
+```text
+id: String
+participants: *
+    name:
+        firstName: String
+        lastName: String
+    age: Int
+    city: String
+```
+
+- `participants` is `FrameColumn`
+- `name` is `ColumnGroup`
+
+Here's the data schema that matches it:
+
+```kotlin
+@DataSchema
+data class Group(
+    val id: String, 
+    val participants: List<Person>
+)
+
+@DataSchema
+data class Person(
+    val name: Name,
+    val age: Int, 
+    val city: String?
+)
+
+@DataSchema
+data class Name(
+    val firstName: String,
+    val lastName: String,
+)
+```
+
+```kotlin
+val url = "https://raw.githubusercontent.com/Kotlin/dataframe/refs/heads/master/data/participants.json"
+val df = DataFrame.readJson(url).cast<Group>()
+```
+
+