Merge pull request #1339 from Kotlin/data_schemas_docs

Data schemas docs

Author: AndreiKingsley

docs/StardustDocs/d.tree

@@ -32,20 +32,19 @@
         <toc-element topic="hierarchical.md"/>
         <toc-element topic="nanAndNa.md"/>
         <toc-element topic="numberUnification.md"/>
-        <toc-element topic="schemas.md">
+    </toc-element>
+    <toc-element topic="extensionPropertiesApi.md"/>
+    <toc-element topic="schemas.md">
+        <toc-element topic="DataSchemaGenerationMethods.md"/>
+        <toc-element topic="schemasInheritance.md"/>
+        <toc-element topic="Data-Schemas-In-Kotlin-Notebook.md"/>
+        <toc-element topic="schemasImportOpenApiJupyter.md"/>
+        <toc-element topic="Gradle-Plugin.md">
             <toc-element topic="schemasGradle.md"/>
-            <toc-element topic="schemasJupyter.md"/>
-            <toc-element topic="schemasInheritance.md"/>
-            <toc-element topic="schemasCustom.md"/>
-            <toc-element topic="schemasExternalJupyter.md"/>
             <toc-element topic="schemasImportSqlGradle.md"/>
             <toc-element topic="schemasImportOpenApiGradle.md"/>
-            <toc-element topic="schemasImportOpenApiJupyter.md"/>
-            <toc-element topic="DataSchemaGenerationGradle.md"/>
         </toc-element>
     </toc-element>
-    <toc-element topic="extensionPropertiesApi.md"/>
-    <toc-element topic="DataSchemaGenerationMethods.md"/>
     <toc-element topic="Compiler-Plugin.md">
         <toc-element topic="staticInterpretation.md"/>
         <toc-element topic="dataSchema.md"/>
@@ -194,4 +193,5 @@
     <toc-element topic="_shadow_resources.md" hidden="true"/>
     <toc-element topic="Support.md"/>
     <toc-element topic="FAQ.md"/>
+    <toc-element topic="Migration-From-Plugins.md"/>
 </instance-profile>

docs/StardustDocs/topics/FAQ.md

@@ -174,15 +174,18 @@ and examples with beautiful [Kandy](https://kotlin.github.io/kandy) geo visualiz
 
 > The current Gradle plugin is **under consideration for deprecation** and may be officially marked as deprecated 
 > in future releases.
-> The KSP plugin doesn't work for now.
+>
+> The KSP plugin is **not compatible with [KSP2](https://github.com/google/ksp?tab=readme-ov-file#ksp2-is-here)**
+> and may **not work properly with Kotlin 2.1 or newer**.
 >
 > At the moment, **[data schema generation is handled via dedicated methods](DataSchemaGenerationMethods.md)** instead 
-> of relying on the plugins.
+> of relying on the plugins. 
+> See [](Migration-From-Plugins.md).
 {style="warning"}
 
 All these plugins relate to working with [dataframe schemas](schemas.md), but they serve different purposes:
 
-- **[Gradle Plugin](DataSchemaGenerationGradle.md)** and **[KSP Plugin](https://github.com/Kotlin/dataframe/tree/master/plugins/symbol-processor)** 
+- **[Gradle Plugin](Gradle-Plugin.md)** and **[KSP Plugin](https://github.com/Kotlin/dataframe/tree/master/plugins/symbol-processor)** 
  are used to **generate data schemas** from external sources as part of the Gradle build process.
 
     - **Gradle Plugin**: You declare the data source in your `build.gradle.kts` file  
@@ -193,12 +196,13 @@ All these plugins relate to working with [dataframe schemas](schemas.md), but th
 
   See [Data Schemas in Gradle Projects](https://kotlin.github.io/dataframe/schemasgradle.html) for more.
 
-- **[Compiler Plugin](Compiler-Plugin.md)**
- provides **on-the-fly generation** of [extension properties](extensionPropertiesApi.md)  
- based on an existing schema **during compilation**.
- However, when reading data from files or external sources (like SQL),
- the schema cannot be inferred automatically — you need to 
- specify it manually or use the Gradle or KSP plugin to generate it.
+- **[Compiler Plugin](Compiler-Plugin.md)** provides **on-the-fly generation** of 
+[extension properties](extensionPropertiesApi.md)
+based on an existing schema **during compilation**, and updates the [`DataFrame`](DataFrame.md)
+schema seamlessly after operations.
+However, when reading data from files or external sources (like SQL),
+the initial `DataFrame` schema cannot be inferred automatically —
+you need to specify it manually or generate it using the [`generate..()` methods](DataSchemaGenerationMethods.md).
 
 ## How do I contribute or report an issue?
 

docs/StardustDocs/topics/concepts/schemas.md

@@ -517,7 +517,7 @@ The Gradle plugin allows generating [data schemas](schemas.md) from samples of d
 (of supported formats) like JSON, CSV, Excel files, or URLs, as well as from data fetched from SQL databases  
 using Gradle.
 
-See the [Gradle Plugin Reference](DataSchemaGenerationGradle.md) for installation  
+See the [Gradle Plugin Reference](Gradle-Plugin.md) for installation  
 and usage instructions in Gradle projects.
 
 > By default, the Gradle plugin also applies the [KSP plugin](#ksp-plugin).

docs/StardustDocs/topics/concepts/schemasCustom.md

@@ -129,7 +129,7 @@ fun createAndPopulateTable(con: Connection) {
 
 **Define the Table Schema**
 
-Use the `@DataSchema` annotation to define a [**custom data schema**](schemasCustom.md) for the `orders` table.
+Use the `@DataSchema` annotation to define a [**custom data schema**](schemas.md) for the `orders` table.
 
 ```kotlin
 @DataSchema