Merge branch 'master' into unsupported-data-sources-examples

# Conflicts:
#	settings.gradle.kts

Author: Jolanrensen

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/html.kt

@@ -77,7 +77,14 @@ internal val formatter = DataFrameFormatter(
 internal fun getResources(vararg resource: String) = resource.joinToString(separator = "\n") { getResourceText(it) }
 
 internal fun getResourceText(resource: String, vararg replacement: Pair<String, Any>): String {
-    val res = DataFrame::class.java.getResourceAsStream(resource) ?: error("Resource '$resource' not found")
+    /**
+     * The choice of loader is crucial here: it should always be a class loaded by the same class loader as the resource we load.
+     * I.e. [DataFrame] isn't a good fit because it might be loaded by Kotlin IDEA plugin (because Kotlin plugin
+     * loads DataFrame compiler plugin), and plugin's classloader knows nothing about the resources.
+     */
+    val loader = HtmlContent::class.java
+    val res = loader.getResourceAsStream(resource)
+        ?: error("Resource '$resource' not found. Load was attempted by $loader, loaded by ${loader.classLoader}")
     var template = InputStreamReader(res).readText()
     replacement.forEach {
         template = template.replace(it.first, it.second.toString())

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/html.kt

@@ -77,7 +77,14 @@ internal val formatter = DataFrameFormatter(
 internal fun getResources(vararg resource: String) = resource.joinToString(separator = "\n") { getResourceText(it) }
 
 internal fun getResourceText(resource: String, vararg replacement: Pair<String, Any>): String {
-    val res = DataFrame::class.java.getResourceAsStream(resource) ?: error("Resource '$resource' not found")
+    /**
+     * The choice of loader is crucial here: it should always be a class loaded by the same class loader as the resource we load.
+     * I.e. [DataFrame] isn't a good fit because it might be loaded by Kotlin IDEA plugin (because Kotlin plugin
+     * loads DataFrame compiler plugin), and plugin's classloader knows nothing about the resources.
+     */
+    val loader = HtmlContent::class.java
+    val res = loader.getResourceAsStream(resource)
+        ?: error("Resource '$resource' not found. Load was attempted by $loader, loaded by ${loader.classLoader}")
     var template = InputStreamReader(res).readText()
     replacement.forEach {
         template = template.replace(it.first, it.second.toString())

docs/StardustDocs/topics/Compiler-Plugin.md

@@ -1,9 +1,34 @@
 # Kotlin DataFrame Compiler Plugin
 
-Kotlin DataFrame compiler plugin: available in Gradle projects, is coming to Kotlin Notebook and Maven projects soon.
+<web-summary>
+Explore the Kotlin DataFrame Compiler Plugin —  
+a powerful tool providing on-the-fly type-safe column-accessors for dataframes.
+</web-summary>
 
-Check out this video that shows how expressions update the schema of a dataframe: 
+<card-summary>
+Explore the Kotlin DataFrame Compiler Plugin —  
+a powerful tool providing on-the-fly type-safe column-accessors for dataframes.
+</card-summary>
+
+<link-summary>
+Explore the Kotlin DataFrame Compiler Plugin —  
+a powerful tool providing on-the-fly type-safe column-accessors for dataframes.
+</link-summary>
+
+
+> Now available in Gradle projects, is coming soon to Kotlin Notebook and Maven projects.
+
+**Kotlin DataFrame Compiler Plugin** is a Kotlin compiler plugin that automatically generates  
+**[type-safe extension properties](extensionPropertiesApi.md)** for your dataframes,  
+allowing you to access columns and row values in a type-safe way and avoid mistakes in column names.
 
+## Why use it?
+
+- Access columns as regular properties: `df.name` instead of `df["name"]`.
+- Get full IDE and compiler support: autocompletion, refactoring, and type checking.
+- Improve code readability and safety when working with DataFrame.
+
+Check out this video that shows how expressions update the schema of a dataframe: 
 
 <video src="compiler_plugin.mp4" controls=""/>
 
@@ -113,3 +138,9 @@ fun main() {
 ```
 
 [Learn more](dataSchema.md) about data schema declarations
+
+## Examples
+
+* [Kotlin DataFrame in the IntelliJ IDEA project example](https://github.com/Kotlin/dataframe/blob/master/examples/kotlin-dataframe-plugin-example)  
+  — an IntelliJ IDEA project showcasing simple DataFrame expressions using the Compiler Plugin.
+* [](compilerPluginExamples.md) — few examples of Compiler Plugin usages.

docs/StardustDocs/topics/Home.topic

@@ -28,6 +28,7 @@
         <secondary>
             <title>Featured topics</title>
             <a href="Kotlin-DataFrame-Features-in-Kotlin-Notebook.md"/>
+            <a href="Compiler-Plugin.md"/>
             <a href="readSqlDatabases.md"/>
         </secondary>
 

docs/StardustDocs/topics/compilerPluginExamples.md

@@ -3,6 +3,9 @@
 This page provides a few examples that you can copy directly to your project.
 [Schema info](staticInterpretation.md#schema-info) will be a convenient way to observe the result of different operations.
 
+> See also an [IntelliJ IDEA project example](https://github.com/Kotlin/dataframe/blob/master/examples/kotlin-dataframe-plugin-example), 
+> showcasing simple DataFrame expressions using the Compiler Plugin.
+
 ### Example 1
 
 ```kotlin

docs/StardustDocs/topics/guides/Guides-And-Examples.md

@@ -56,6 +56,11 @@ Explore our structured, in-depth guides to steadily improve your Kotlin DataFram
 
 Explore our extensive collection of practical examples and real-world analytics workflows.
 
+* [Kotlin DataFrame Compiler Plugin Example](https://github.com/Kotlin/dataframe/blob/master/examples/kotlin-dataframe-plugin-example)  
+  — a simple project demonstrating the usage of the [compiler plugin](Compiler-Plugin.md),  
+  showcasing DataFrame expressions with [extension properties](extensionPropertiesApi.md)  
+  that are generated on-the-fly in the IDEA project.
+
 * [Titanic Example](https://github.com/Kotlin/dataframe/blob/master/examples/notebooks/titanic/Titanic.ipynb)
   — discover the famous "Titanic"
   dataset with the Kotlin DataFrame analysis toolkit

examples/README.md

@@ -1,6 +1,8 @@
 # Examples of Kotlin Dataframe
 
 ### Idea examples
+* [plugin example](kotlin-dataframe-plugin-example) IDEA project with a 
+[Kotlin DataFrame Compiler Plugin](https://kotlin.github.io/dataframe/compiler-plugin.html) example.
 * [movies](idea-examples/movies) Using extension properties [Access API](https://kotlin.github.io/dataframe/apilevels.html) to perform a data cleaning task
 * [titanic](idea-examples/titanic)
 * [youtube](idea-examples/youtube)

examples/kotlin-dataframe-plugin-example/README.md

@@ -0,0 +1,10 @@
+# Kotlin DataFrame Compiler Plugin Example
+
+An IntelliJ IDEA project demonstrating the use of the  
+[Kotlin DataFrame Compiler Plugin](https://kotlin.github.io/dataframe/compiler-plugin.html).
+
+> **Note:** This project uses **dev versions** of the Kotlin and the Kotlin DataFrame plugin.  
+> See [build.gradle.kts](build.gradle.kts) for details.
+
+For proper functionality in IntelliJ IDEA requires version 2025.2 or higher 
+(Currently available only in [IntelliJ IDEA EAP](https://www.jetbrains.com/idea/nextversion/?_gl=1*1ojxffu*_gcl_au*MTk5NzUwODYzOS4xNzQ2NzkxMDMz*_ga*MTE0ODQ1MzY3OS4xNzM4OTY1NzM3*_ga_9J976DJZ68*czE3NDkyMTM4MzkkbzE5OCRnMSR0MTc0OTIxMzg0MSRqNTgkbDAkaDA.)).

examples/kotlin-dataframe-plugin-example/build.gradle.kts

@@ -0,0 +1,32 @@
+import org.jlleitschuh.gradle.ktlint.KtlintExtension
+
+plugins {
+    id("org.jlleitschuh.gradle.ktlint") version "12.3.0"
+    kotlin("jvm") version "2.2.20-dev-3524"
+    kotlin("plugin.dataframe") version "2.2.20-dev-3524"
+}
+
+group = "org.example"
+version = "1.0-SNAPSHOT"
+
+repositories {
+    maven("https://packages.jetbrains.team/maven/p/kt/dev/")
+    mavenCentral()
+}
+
+dependencies {
+    implementation("org.jetbrains.kotlinx:dataframe:1.0.0-Beta2")
+    testImplementation(kotlin("test"))
+}
+
+tasks.test {
+    useJUnitPlatform()
+}
+kotlin {
+    jvmToolchain(11)
+}
+
+configure<KtlintExtension> {
+    version = "1.6.0"
+    // rules are set up through .editorconfig
+}

examples/kotlin-dataframe-plugin-example/gradle.properties

@@ -0,0 +1,4 @@
+kotlin.code.style=official
+# Disabling incremental compilation will no longer be necessary
+# when https://youtrack.jetbrains.com/issue/KT-66735 is resolved.
+kotlin.incremental=false