Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Gradle plugin references fix #365

Merged
merged 1 commit into from
Apr 27, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/StardustDocs/topics/extensionPropertiesApi.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,11 @@ df.add("lastName") { name.split(",").last() }
<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.ApiLevels.extensionProperties2.html"/>
<!---END-->

Extension properties are generated for [`DataSchema`](schemas.md) that is extracted from [`DataFrame`](DataFrame.md)
In notebooks, extension properties are generated for [`DataSchema`](schemas.md) that is extracted from [`DataFrame`](DataFrame.md)
instance after REPL line execution.
After that [`DataFrame`](DataFrame.md) variable is typed with its own [`DataSchema`](schemas.md), so only valid extension properties corresponding to actual columns in DataFrame will be allowed by the compiler and suggested by completion.

Also, extension properties [can be generated in IntelliJ IDEA](gradle.md) using the [Kotlin Dataframe Gradle plugin](installation.md#data-schema-preprocessor).
Extension properties can be generated in IntelliJ IDEA using the [Kotlin Dataframe Gradle plugin](gradle.md#configuration).

<warning>
In notebooks generated properties won't appear and be updated until the cell has been executed. It often means that you have to introduce new variable frequently to sync extension properties with actual schema
Expand Down
59 changes: 48 additions & 11 deletions docs/StardustDocs/topics/gradle.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,46 @@

<!---IMPORT org.jetbrains.kotlinx.dataframe.samples.api.Schemas-->

In Gradle project the Kotlin DataFrame library provides
In Gradle projects, the Kotlin DataFrame library provides

1. Annotation processing for generation of extension properties
2. Annotation processing for [`DataSchema`](schemas.md) inference from datasets.
3. Gradle task for [`DataSchema`](schemas.md) inference from datasets.

### Configuration

To use [extension properties API](extensionPropertiesApi.md) in Gradle project you
should [configure the Kotlin DataFrame plugin](installation.md#data-schema-preprocessor).
To use the [extension properties API](extensionPropertiesApi.md) in Gradle project add the `dataframe` plugin as follows:

<tabs>
<tab title="Kotlin DSL">

```kotlin
plugins {
id("org.jetbrains.kotlinx.dataframe") version "%dataFrameVersion%"
}

dependencies {
implementation("org.jetbrains.kotlinx:dataframe:%dataFrameVersion%")
}
```

</tab>

<tab title="Groovy DSL">

```groovy
plugins {
id("org.jetbrains.kotlinx.dataframe") version "%dataFrameVersion%"
}

dependencies {
implementation 'org.jetbrains.kotlinx:dataframe:%dataFrameVersion%'
}
```

</tab>

</tabs>

### Annotation processing

Expand Down Expand Up @@ -52,14 +82,21 @@ Specify schema with preferred method and execute the `assemble` task.
<tabs>
<tab title="Method 1. Annotation processing">

`@ImportDataSchema` annotation must be above package directive. You can put this annotation in the same file as data
processing code. You can import schema from URL or relative path of the file. Relative path by default is resolved to
project root directory. You can configure it
by [passing](https://kotlinlang.org/docs/ksp-quickstart.html#pass-options-to-processors) `dataframe.resolutionDir`
option to preprocessor
`@ImportDataSchema` annotation must be above package directive.
You can import schemas from a URL or from the relative path of a file.
Relative path by default is resolved to the project root directory.
You can configure it by [passing](https://kotlinlang.org/docs/ksp-quickstart.html#pass-options-to-processors) `dataframe.resolutionDir`
option to preprocessor.
For example:

```kotlin
ksp {
arg("dataframe.resolutionDir", file("data").absolutePath)
}
```

**Note that due to incremental processing, imported schema will be re-generated only if some source code has changed
from previous invocation, at least one character**
from the previous invocation, at least one character.**

For the following configuration, file `Repository.Generated.kt` will be generated to `build/generated/ksp/` folder in
the same package as file containing the annotation.
Expand All @@ -75,8 +112,8 @@ import org.jetbrains.kotlinx.dataframe.api.*
```

See KDocs for `@ImportDataSchema` in IDE
or [github](https://github.com/Kotlin/dataframe/blob/master/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/annotations/ImportDataSchema.kt)
for more details
or [GitHub](https://github.com/Kotlin/dataframe/blob/master/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/annotations/ImportDataSchema.kt)
for more details.

</tab>

Expand Down
2 changes: 1 addition & 1 deletion docs/StardustDocs/topics/schemas.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ It ignores order of columns in [`DataFrame`](DataFrame.md), but tracks column hi

In Jupyter environment compile-time [`DataFrame`](DataFrame.md) schema is synchronized with real-time data after every cell execution.

In IDEA projects you can use [gradle plugin](installation.md#data-schema-preprocessor) to extract schema from dataset
In IDEA projects, you can use the [Gradle plugin](gradle.md#configuration) to extract schema from the dataset
and generate extension properties.

## DataSchema workflow in Jupyter
Expand Down