Skip to content

Commit 4ef1a22

Browse files
koperagenkoperagen
authored
Merge pull request #560 from Kotlin/documentation-updates
Documentation updates
2 parents 8673b05 + f3e7e97 commit 4ef1a22

File tree

147 files changed

+2005
-5267
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

147 files changed

+2005
-5267
lines changed

‎README.md

+58-122
Original file line numberDiff line numberDiff line change
@@ -37,143 +37,65 @@ You could find the following articles there:
3737

3838
## Setup
3939

40-
### Gradle for JVM
41-
```groovy
42-
// build.gradle
43-
44-
plugins {
45-
// Optional Gradle plugin for enhanced type safety and schema generation
46-
// https://kotlin.github.io/dataframe/gradle.html
47-
id 'org.jetbrains.kotlinx.dataframe' version '0.12.0'
48-
}
49-
50-
repositories {
51-
mavenCentral()
52-
}
53-
54-
dependencies {
55-
implementation 'org.jetbrains.kotlinx:dataframe:0.12.0'
56-
}
40+
```kotlin
41+
implementation("org.jetbrains.kotlinx:dataframe:0.12.1")
5742
```
5843

44+
Optional Gradle plugin for enhanced type safety and schema generation
45+
https://kotlin.github.io/dataframe/schemasgradle.html
5946
```kotlin
60-
// build.gradle.kts
61-
62-
plugins {
63-
// Optional Gradle plugin for enhanced type safety and schema generation
64-
// https://kotlin.github.io/dataframe/gradle.html
65-
id("org.jetbrains.kotlinx.dataframe") version "0.12.0"
66-
}
67-
68-
repositories {
69-
mavenCentral()
70-
}
71-
72-
dependencies {
73-
implementation("org.jetbrains.kotlinx:dataframe:0.12.0")
74-
}
47+
id("org.jetbrains.kotlinx.dataframe") version "0.12.1"
7548
```
7649

77-
### Gradle for Android
78-
```groovy
79-
// build.gradle
80-
81-
plugins {
82-
// Optional Gradle plugin for enhanced type safety and schema generation
83-
// https://kotlin.github.io/dataframe/gradle.html
84-
id 'org.jetbrains.kotlinx.dataframe' version '0.12.0'
85-
}
50+
Check out the [custom setup page](https://kotlin.github.io/dataframe/gettingstartedgradleadvanced.html) if you don't need some of the formats as dependencies,
51+
for Groovy, and for configurations specific to Android projects.
8652

87-
dependencies {
88-
implementation 'org.jetbrains.kotlinx:dataframe:0.12.0'
89-
}
53+
## Getting started
9054

91-
android {
92-
defaultConfig {
93-
minSdk 26 // Android O+
94-
}
95-
compileOptions {
96-
sourceCompatibility JavaVersion.VERSION_1_8
97-
targetCompatibility JavaVersion.VERSION_1_8
98-
}
99-
kotlinOptions {
100-
jvmTarget = '1.8'
101-
}
102-
packagingOptions {
103-
resources {
104-
pickFirsts = ["META-INF/AL2.0",
105-
"META-INF/LGPL2.1",
106-
"META-INF/ASL-2.0.txt",
107-
"META-INF/LICENSE.md",
108-
"META-INF/NOTICE.md",
109-
"META-INF/LGPL-3.0.txt"]
110-
excludes = ["META-INF/kotlin-jupyter-libraries/libraries.json",
111-
"META-INF/{INDEX.LIST,DEPENDENCIES}",
112-
"{draftv3,draftv4}/schema",
113-
"arrow-git.properties"]
114-
}
115-
}
116-
}
117-
118-
// optional, could be required for KSP
119-
tasks.withType(KotlinCompile).configureEach {
120-
kotlinOptions {
121-
jvmTarget = '1.8'
122-
}
123-
}
55+
```kotlin
56+
import org.jetbrains.kotlinx.dataframe.*
57+
import org.jetbrains.kotlinx.dataframe.api.*
58+
import org.jetbrains.kotlinx.dataframe.io.*
12459
```
12560

12661
```kotlin
127-
// build.gradle.kts
62+
val df = DataFrame.read("https://raw.githubusercontent.com/Kotlin/dataframe/master/data/jetbrains_repositories.csv")
63+
df["full_name"][0] // Indexing https://kotlin.github.io/dataframe/access.html
12864

129-
plugins {
130-
// Optional Gradle plugin for enhanced type safety and schema generation
131-
// https://kotlin.github.io/dataframe/gradle.html
132-
id("org.jetbrains.kotlinx.dataframe") version "0.12.0"
133-
}
65+
df.filter { "stargazers_count"<Int>() > 50 }.print()
66+
```
13467

135-
dependencies {
136-
implementation("org.jetbrains.kotlinx:dataframe:0.12.0")
137-
}
68+
## Getting started with data schema
13869

139-
android {
140-
defaultConfig {
141-
minSdk = 26 // Android O+
142-
}
143-
compileOptions {
144-
sourceCompatibility = JavaVersion.VERSION_1_8
145-
targetCompatibility = JavaVersion.VERSION_1_8
146-
}
147-
kotlinOptions {
148-
jvmTarget = "1.8"
149-
}
150-
packaging {
151-
resources {
152-
pickFirsts += listOf(
153-
"META-INF/AL2.0",
154-
"META-INF/LGPL2.1",
155-
"META-INF/ASL-2.0.txt",
156-
"META-INF/LICENSE.md",
157-
"META-INF/NOTICE.md",
158-
"META-INF/LGPL-3.0.txt",
159-
)
160-
excludes += listOf(
161-
"META-INF/kotlin-jupyter-libraries/libraries.json",
162-
"META-INF/{INDEX.LIST,DEPENDENCIES}",
163-
"{draftv3,draftv4}/schema",
164-
"arrow-git.properties",
165-
)
166-
}
167-
}
168-
}
70+
Requires Gradle plugin to work
71+
```kotlin
72+
id("org.jetbrains.kotlinx.dataframe") version "0.12.1"
73+
```
74+
75+
Plugin generates extension properties API for provided sample of data. Column names and their types become discoverable in completion.
16976

170-
// required for KSP
171-
tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
172-
kotlinOptions.jvmTarget = "1.8"
77+
```kotlin
78+
// Make sure to place the file annotation above the package directive
79+
@file:ImportDataSchema(
80+
"Repository",
81+
"https://raw.githubusercontent.com/Kotlin/dataframe/master/data/jetbrains_repositories.csv",
82+
)
83+
84+
package example
85+
86+
import org.jetbrains.kotlinx.dataframe.annotations.ImportDataSchema
87+
import org.jetbrains.kotlinx.dataframe.api.*
88+
89+
fun main() {
90+
// execute `assemble` to generate extension properties API
91+
val df = Repository.readCSV()
92+
df.fullName[0]
93+
94+
df.filter { stargazersCount > 50 }
17395
}
17496
```
17597

176-
### Jupyter Notebook
98+
## Getting started in Jupyter Notebook / Kotlin Notebook
17799

178100
Install [Kotlin kernel](https://github.com/Kotlin/kotlin-jupyter) for [Jupyter](https://jupyter.org/)
179101

@@ -186,14 +108,26 @@ or specific version:
186108
%use dataframe(<version>)
187109
```
188110

111+
```kotlin
112+
val df = DataFrame.read("https://raw.githubusercontent.com/Kotlin/dataframe/master/data/jetbrains_repositories.csv")
113+
df // the last expression in the cell is displayed
114+
```
115+
116+
When a cell with a variable declaration is executed, in the next cell `DataFrame` provides extension properties based on its data
117+
```kotlin
118+
df.filter { stargazers_count > 50 }
119+
```
120+
189121
## Data model
190122
* `DataFrame` is a list of columns with equal sizes and distinct names.
191123
* `DataColumn` is a named list of values. Can be one of three kinds:
192124
* `ValueColumn` — contains data
193125
* `ColumnGroup` — contains columns
194126
* `FrameColumn` — contains dataframes
195127

196-
## Usage example
128+
## Syntax example
129+
130+
Let us show you how data cleaning and aggregation pipelines could look like with DataFrame.
197131

198132
**Create:**
199133
```kotlin
@@ -269,7 +203,9 @@ clean
269203
}
270204
```
271205

272-
[Try it in **Datalore**](https://datalore.jetbrains.com/view/notebook/vq5j45KWkYiSQnACA2Ymij) and explore [**more examples here**](examples).
206+
Check it out on [**Datalore**](https://datalore.jetbrains.com/view/notebook/vq5j45KWkYiSQnACA2Ymij) to get a better visual impression of what happens and what the hierarchical DataFrame structure looks like.
207+
208+
Explore [**more examples here**](examples).
273209

274210
## Kotlin, Kotlin Jupyter, OpenAPI, Arrow and JDK versions
275211

‎docs/StardustDocs/snippets/org.jetbrains.kotlinx.dataframe.samples.api.Access.byRow.html

+15-51
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
<html>
2-
<head>
3-
<style type="text/css">
4-
:root {
1+
<html>
2+
<head>
3+
<style type="text/css">
4+
:root {
55
--background: #fff;
66
--background-odd: #f5f5f5;
77
--background-hover: #d9edfd;
@@ -173,34 +173,12 @@
173173
summary {
174174
padding: 6px;
175175
}
176-
177-
178-
179-
180-
181-
182-
183-
184-
185-
186-
187-
188-
189-
190-
191-
192-
193-
194-
195-
</style>
196-
</head>
197-
<body>
198-
199-
176+
</style>
177+
</head>
178+
<body>
200179
<details>
201180
<summary>df.df[0].name</summary>
202-
203-
<details>
181+
<details>
204182
<summary>Input DataFrame: rowsCount = 7, columnsCount = 5</summary>
205183
<table class="dataframe" id="df_0"></table>
206184

@@ -222,8 +200,7 @@
222200
<br>
223201
<details>
224202
<summary>df.df[3, 5, 6].select { name and age }</summary>
225-
226-
<details>
203+
<details>
227204
<summary>Input DataFrame: rowsCount = 7, columnsCount = 5</summary>
228205
<table class="dataframe" id="df_3"></table>
229206

@@ -245,8 +222,7 @@
245222
<br>
246223
<details>
247224
<summary>df.df[3..5]</summary>
248-
249-
<details>
225+
<details>
250226
<summary>Input DataFrame: rowsCount = 7, columnsCount = 5</summary>
251227
<table class="dataframe" id="df_6"></table>
252228

@@ -260,9 +236,9 @@
260236
</details>
261237
</details>
262238
<br>
263-
</body>
264-
<script>
265-
(function () {
239+
</body>
240+
<script>
241+
(function () {
266242
window.DataFrame = window.DataFrame || new (function () {
267243
this.addTable = function (df) {
268244
let cols = df.cols;
@@ -536,8 +512,6 @@
536512
}
537513
})()
538514

539-
540-
541515
/*<!--*/
542516
call_DataFrame(function() { DataFrame.addTable({ cols: [{ name: "<span title=\"firstName: String\">firstName</span>", children: [], rightAlign: false, values: ["Alice","Bob","Charlie","Charlie","Bob","Alice","Charlie"] },
543517
{ name: "<span title=\"lastName: String\">lastName</span>", children: [], rightAlign: false, values: ["Cooper","Dylan","Daniels","Chaplin","Marley","Wolf","Byrd"] },
@@ -551,7 +525,6 @@
551525

552526
call_DataFrame(function() { DataFrame.renderTable(0) });
553527

554-
555528
/*<!--*/
556529
call_DataFrame(function() { DataFrame.addTable({ cols: [{ name: "<span title=\"firstName: String\">firstName</span>", children: [], rightAlign: false, values: ["Alice"] },
557530
{ name: "<span title=\"lastName: String\">lastName</span>", children: [], rightAlign: false, values: ["Cooper"] },
@@ -565,7 +538,6 @@
565538

566539
call_DataFrame(function() { DataFrame.renderTable(1) });
567540

568-
569541
/*<!--*/
570542
call_DataFrame(function() { DataFrame.addTable({ cols: [{ name: "<span title=\"firstName: String\">firstName</span>", children: [], rightAlign: false, values: ["Alice"] },
571543
{ name: "<span title=\"lastName: String\">lastName</span>", children: [], rightAlign: false, values: ["Cooper"] },
@@ -574,8 +546,6 @@
574546

575547
call_DataFrame(function() { DataFrame.renderTable(2) });
576548

577-
578-
579549
/*<!--*/
580550
call_DataFrame(function() { DataFrame.addTable({ cols: [{ name: "<span title=\"firstName: String\">firstName</span>", children: [], rightAlign: false, values: ["Alice","Bob","Charlie","Charlie","Bob","Alice","Charlie"] },
581551
{ name: "<span title=\"lastName: String\">lastName</span>", children: [], rightAlign: false, values: ["Cooper","Dylan","Daniels","Chaplin","Marley","Wolf","Byrd"] },
@@ -589,7 +559,6 @@
589559

590560
call_DataFrame(function() { DataFrame.renderTable(3) });
591561

592-
593562
/*<!--*/
594563
call_DataFrame(function() { DataFrame.addTable({ cols: [{ name: "<span title=\"firstName: String\">firstName</span>", children: [], rightAlign: false, values: ["Charlie","Alice","Charlie"] },
595564
{ name: "<span title=\"lastName: String\">lastName</span>", children: [], rightAlign: false, values: ["Chaplin","Wolf","Byrd"] },
@@ -603,7 +572,6 @@
603572

604573
call_DataFrame(function() { DataFrame.renderTable(4) });
605574

606-
607575
/*<!--*/
608576
call_DataFrame(function() { DataFrame.addTable({ cols: [{ name: "<span title=\"firstName: String\">firstName</span>", children: [], rightAlign: false, values: ["Charlie","Alice","Charlie"] },
609577
{ name: "<span title=\"lastName: String\">lastName</span>", children: [], rightAlign: false, values: ["Chaplin","Wolf","Byrd"] },
@@ -614,8 +582,6 @@
614582

615583
call_DataFrame(function() { DataFrame.renderTable(5) });
616584

617-
618-
619585
/*<!--*/
620586
call_DataFrame(function() { DataFrame.addTable({ cols: [{ name: "<span title=\"firstName: String\">firstName</span>", children: [], rightAlign: false, values: ["Alice","Bob","Charlie","Charlie","Bob","Alice","Charlie"] },
621587
{ name: "<span title=\"lastName: String\">lastName</span>", children: [], rightAlign: false, values: ["Cooper","Dylan","Daniels","Chaplin","Marley","Wolf","Byrd"] },
@@ -629,7 +595,6 @@
629595

630596
call_DataFrame(function() { DataFrame.renderTable(6) });
631597

632-
633598
/*<!--*/
634599
call_DataFrame(function() { DataFrame.addTable({ cols: [{ name: "<span title=\"firstName: String\">firstName</span>", children: [], rightAlign: false, values: ["Charlie","Bob","Alice"] },
635600
{ name: "<span title=\"lastName: String\">lastName</span>", children: [], rightAlign: false, values: ["Chaplin","Marley","Wolf"] },
@@ -643,6 +608,5 @@
643608

644609
call_DataFrame(function() { DataFrame.renderTable(7) });
645610

646-
647-
</script>
648-
</html>
611+
</script>
612+
</html>

0 commit comments

Comments
 (0)