Skip to content

Commit e92a8f6

Browse files
JolanrensenJolanrensen
committed
creating documentation for format
1 parent 6b2ca7b commit e92a8f6

26 files changed

+1368
-323
lines changed

‎core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/convert.kt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -649,7 +649,7 @@ public inline fun <T, C, R> Convert<T, C>.asColumn(
649649
* ```kotlin
650650
* // Convert values in all columns to `String` and add their column name to the end
651651
* df.convert { all() }.perRowCol { row, col ->
652-
* row[col].toString() + col.name()
652+
* col[row].toString() + col.name()
653653
* }
654654
* ```
655655
*

‎core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/format.kt

Lines changed: 242 additions & 50 deletions
Large diffs are not rendered by default.

‎core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DslGrammar.kt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ package org.jetbrains.kotlinx.dataframe.documentation
33
/**
44
* ## DSL Grammar
55
*
6-
* If you've come across notations like **`a(`** `(`**`b`**` | [`**`c, .. `**`] )` **`)`**
6+
* If you've come across notations like **`a(`**` (`**`b`**` | [`**`c, .. `**`] ) `**`)`**
77
* either in the KDocs or on the website and would like some further explanation
88
* for what it means, you've come to the right place.
99
*

‎core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/api/format.kt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ internal inline fun <T, C> FormatClause<T, C>.formatImpl(
5656
val columns =
5757
if (clause.columns != null) {
5858
clause.df.getColumnsWithPaths(clause.columns)
59-
.mapNotNull { if (it.depth == 0) it.name else null }
59+
.mapNotNull { if (it.depth == 0) it.name else null } // TODO Causes #1356
6060
.toSet()
6161
} else {
6262
null

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

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -171,15 +171,15 @@ internal fun AnyFrame.toHtmlData(
171171
}
172172
val renderConfig = configuration.copy(decimalFormat = format)
173173
val contents = values.map {
174-
val value = it[col]
174+
val value = col[it]
175175
val content = value.toDataFrameLikeOrNull()
176176
if (content != null) {
177177
val df = content.df()
178178
if (df.isEmpty()) {
179179
HtmlContent("", null)
180180
} else {
181181
val id = nextTableId()
182-
queue.add(RenderingQueueItem(df, id, content.configuration(defaultConfiguration)))
182+
queue += RenderingQueueItem(df, id, content.configuration(defaultConfiguration))
183183
DataFrameReference(id, df.size)
184184
}
185185
} else {
@@ -189,6 +189,21 @@ internal fun AnyFrame.toHtmlData(
189189
?.invoke(FormattingDsl, it, col)
190190
?.attributes()
191191
?.ifEmpty { null }
192+
?.flatMap {
193+
if (it.first == "color") {
194+
// override all --text-color* variables that
195+
// are used to color text of .numbers, .null, etc., inside DataFrame
196+
listOf(
197+
it,
198+
"--text-color" to "${it.second} !important",
199+
"--text-color-dark" to "${it.second} !important",
200+
"--text-color-pale" to "${it.second} !important",
201+
"--text-color-medium" to "${it.second} !important",
202+
)
203+
} else {
204+
listOf(it)
205+
}
206+
}
192207
?.joinToString(";") { "${it.first}:${it.second}" }
193208
HtmlContent(html, style)
194209
}
@@ -207,7 +222,7 @@ internal fun AnyFrame.toHtmlData(
207222
}
208223

209224
val rootId = nextTableId()
210-
queue.add(RenderingQueueItem(this, rootId, defaultConfiguration))
225+
queue += RenderingQueueItem(this, rootId, defaultConfiguration)
211226
while (!queue.isEmpty()) {
212227
val (nextDf, nextId, configuration) = queue.pop()
213228
val rowsLimit = if (nextId == rootId) configuration.rowsLimit else configuration.nestedRowsLimit
@@ -550,9 +565,10 @@ public fun <T> DataFrame<T>.toStandaloneHTML(
550565
* To change the formatting of certain cells or columns in the dataframe,
551566
* use [DataFrame.format].
552567
*
553-
* The [DataFrameHtmlData] be saved as an *.html file and displayed in the browser.
568+
* The [DataFrameHtmlData] can be saved as an *.html file and displayed in the browser.
554569
* If you save it as a file and find it in the project tree,
555-
* the ["Open in browser"](https://www.jetbrains.com/help/idea/editing-html-files.html#ws_html_preview_output_procedure) feature of IntelliJ IDEA will automatically reload the file content when it's updated
570+
* the ["Open in browser"](https://www.jetbrains.com/help/idea/editing-html-files.html#ws_html_preview_output_procedure)
571+
* feature of IntelliJ IDEA will automatically reload the file content when it's updated.
556572
* @return DataFrameHtmlData with table script and css definitions
557573
*/
558574
public fun <T> DataFrame<T>.toStandaloneHtml(

‎core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Modify.kt

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,16 @@
33
package org.jetbrains.kotlinx.dataframe.samples.api
44

55
import io.kotest.matchers.shouldBe
6+
import org.jetbrains.kotlinx.dataframe.DataColumn
67
import org.jetbrains.kotlinx.dataframe.DataFrame
78
import org.jetbrains.kotlinx.dataframe.DataRow
89
import org.jetbrains.kotlinx.dataframe.alsoDebug
910
import org.jetbrains.kotlinx.dataframe.annotations.DataSchema
11+
import org.jetbrains.kotlinx.dataframe.api.FormattingDsl
1012
import org.jetbrains.kotlinx.dataframe.api.ParserOptions
1113
import org.jetbrains.kotlinx.dataframe.api.add
1214
import org.jetbrains.kotlinx.dataframe.api.after
15+
import org.jetbrains.kotlinx.dataframe.api.and
1316
import org.jetbrains.kotlinx.dataframe.api.asColumn
1417
import org.jetbrains.kotlinx.dataframe.api.to
1518
import org.jetbrains.kotlinx.dataframe.api.asFrame
@@ -36,6 +39,7 @@ import org.jetbrains.kotlinx.dataframe.api.fillNaNs
3639
import org.jetbrains.kotlinx.dataframe.api.fillNulls
3740
import org.jetbrains.kotlinx.dataframe.api.filter
3841
import org.jetbrains.kotlinx.dataframe.api.flatten
42+
import org.jetbrains.kotlinx.dataframe.api.format
3943
import org.jetbrains.kotlinx.dataframe.api.gather
4044
import org.jetbrains.kotlinx.dataframe.api.getRows
4145
import org.jetbrains.kotlinx.dataframe.api.group
@@ -51,6 +55,7 @@ import org.jetbrains.kotlinx.dataframe.api.intoRows
5155
import org.jetbrains.kotlinx.dataframe.api.inward
5256
import org.jetbrains.kotlinx.dataframe.api.keysInto
5357
import org.jetbrains.kotlinx.dataframe.api.length
58+
import org.jetbrains.kotlinx.dataframe.api.linearBg
5459
import org.jetbrains.kotlinx.dataframe.api.lowercase
5560
import org.jetbrains.kotlinx.dataframe.api.map
5661
import org.jetbrains.kotlinx.dataframe.api.mapKeys
@@ -62,6 +67,7 @@ import org.jetbrains.kotlinx.dataframe.api.max
6267
import org.jetbrains.kotlinx.dataframe.api.mean
6368
import org.jetbrains.kotlinx.dataframe.api.meanFor
6469
import org.jetbrains.kotlinx.dataframe.api.merge
70+
import org.jetbrains.kotlinx.dataframe.api.min
6571
import org.jetbrains.kotlinx.dataframe.api.minus
6672
import org.jetbrains.kotlinx.dataframe.api.move
6773
import org.jetbrains.kotlinx.dataframe.api.named
@@ -1303,4 +1309,38 @@ class Modify : TestBase() {
13031309
}
13041310
// SampleEnd
13051311
}
1312+
1313+
@Test
1314+
fun formatExample_properties() {
1315+
// SampleStart
1316+
df
1317+
.format().with { bold and textColor(black) }
1318+
.format { isHappy }.with { background(if (it) green else red) }
1319+
.format { weight }.notNull().linearBg(50 to FormattingDsl.blue, 90 to FormattingDsl.red)
1320+
.format { age }.perRowCol { row, col ->
1321+
textColor(
1322+
linear(value = col[row], from = col.min() to blue, to = col.max() to green)
1323+
)
1324+
}
1325+
.toStandaloneHtml()
1326+
// SampleEnd
1327+
}
1328+
1329+
@Suppress("UNCHECKED_CAST")
1330+
@Test
1331+
fun formatExample_strings() {
1332+
// SampleStart
1333+
df
1334+
.format().with { bold and textColor(black) }
1335+
.format("isHappy").with { background(if (it as Boolean) green else red) }
1336+
.format("weight").notNull().with { linearBg(it as Int, 50 to blue, 90 to red) }
1337+
.format("age").perRowCol { row, col ->
1338+
col as DataColumn<Int>
1339+
textColor(
1340+
linear(value = col[row], from = col.min() to blue, to = col.max() to green)
1341+
)
1342+
}
1343+
.toStandaloneHtml()
1344+
// SampleEnd
1345+
}
13061346
}

‎core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/OtherSamples.kt

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,27 +2,54 @@ package org.jetbrains.kotlinx.dataframe.samples.api
22

33
import org.jetbrains.kotlinx.dataframe.AnyFrame
44
import org.jetbrains.kotlinx.dataframe.DataFrame
5+
import org.jetbrains.kotlinx.dataframe.api.*
6+
import org.jetbrains.kotlinx.dataframe.api.FormattedFrame
57
import org.jetbrains.kotlinx.dataframe.api.take
68
import org.jetbrains.kotlinx.dataframe.explainer.WritersideFooter
79
import org.jetbrains.kotlinx.dataframe.explainer.WritersideStyle
10+
import org.jetbrains.kotlinx.dataframe.io.DisplayConfiguration
811
import org.jetbrains.kotlinx.dataframe.io.read
912
import org.jetbrains.kotlinx.dataframe.io.toStandaloneHtml
1013
import org.junit.Test
1114
import java.io.File
1215

1316
// To display code together with a table, we can use TransformDataFrameExpressions annotation together with korro
1417
// This class provides an ability to save only a table that can be embedded anywhere in the documentation
15-
class OtherSamples {
18+
class OtherSamples : TestBase() {
1619

1720
@Test
1821
fun example() {
1922
val df = DataFrame.read("../data/movies.csv").take(5)
2023
// writeTable(df, "exampleName")
2124
}
2225

26+
@Test
27+
fun formatExample() {
28+
val formattedDf = df
29+
.format().with { bold and textColor(black) }
30+
.format { isHappy }.with { background(if (it) green else red) }
31+
.format { weight }.notNull().linearBg(50 to FormattingDsl.blue, 90 to FormattingDsl.red)
32+
.format { age }.perRowCol { row, col ->
33+
textColor(
34+
linear(value = col[row], from = col.min() to blue, to = col.max() to green),
35+
)
36+
}
37+
38+
writeTable(formattedDf, "formatExample")
39+
}
40+
2341
private fun writeTable(df: AnyFrame, name: String) {
2442
val dir = File("../docs/StardustDocs/resources/snippets/manual").also { it.mkdirs() }
2543
val html = df.toStandaloneHtml(getFooter = WritersideFooter) + WritersideStyle
2644
html.writeHtml(File(dir, "$name.html"))
2745
}
46+
47+
private fun writeTable(formattedDf: FormattedFrame<*>, name: String) {
48+
val dir = File("../docs/StardustDocs/resources/snippets/manual").also { it.mkdirs() }
49+
val html = formattedDf.df.toStandaloneHtml(
50+
configuration = formattedDf.getDisplayConfiguration(DisplayConfiguration.DEFAULT),
51+
getFooter = WritersideFooter,
52+
) + WritersideStyle
53+
html.writeHtml(File(dir, "$name.html"))
54+
}
2855
}

‎core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/format.kt

Lines changed: 40 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -79,43 +79,49 @@ internal interface FormatDocs {
7979
* {@include [LineBreak]}
8080
* {@include [DslGrammarLink]}
8181
*
82-
* ### Definitions:
83-
* {@include [CellFormatterDef]}
84-
* {@include [LineBreak]}
85-
* {@include [RowColFormatterDef]}
86-
*
87-
* ### Notation:
88-
*
89-
* [**format**][DataFrame.format]**` { `**[`columns`][SelectingColumns]**` }`**
90-
*
91-
* {@include [Indent]}
92-
* `\[ `__`.`__[**`where`**][FormatClause.where]**` { `**[`filter`][SelectingRows.RowValueCondition]`: `[`RowValueFilter`][RowValueFilter]**` } `**`]`
93-
*
94-
* {@include [Indent]}
95-
* `\[ `__`.`__[**`at`**][FormatClause.at]**`(`**`rowIndices: `[Collection][Collection]`<`[Int][Int]`> | `[IntRange][IntRange]` | `**`vararg`**` `[Int][Int]**`)`**` ]`
96-
*
97-
* {@include [Indent]}
98-
* `\[ `__`.`__[**`notNull`**][FormatClause.notNull]**`()`**` ]`
99-
*
100-
* {@include [Indent]}
101-
* __`.`__[**`with`**][FormatClause.with]**` { `**{@include [CellFormatterRef]}**` }`**
102-
*
103-
* {@include [Indent]}
104-
* `| `__`.`__[**`notNull`**][FormatClause.notNull]**` { `**{@include [CellFormatterRef]}**` }`**
105-
*
106-
* {@include [Indent]}
107-
* `| `__`.`__[**`perRowCol`**][FormatClause.perRowCol]**` { `**{@include [RowColFormatterRef]}**` }`**
108-
*
109-
* {@include [Indent]}
110-
* `| `__`.`__[**`linearBg`**][FormatClause.linearBg]**`(`**`from: `[Pair][Pair]`<`[Number][Number]`, `[RgbColor][RgbColor]`>`**`,`**` to: `[Pair][Pair]`<`[Number][Number]`, `[RgbColor][RgbColor]`>`**`)`**
111-
*
112-
* `\[ `__`.`__[**format**][FormattedFrame.format]` ↺ \]`
113-
* {@include [LineBreak]}
114-
* {@include [FormattingDslGrammarDef]}
82+
* @include [ForHtml]
11583
*/
116-
@ExportAsHtml
11784
interface Grammar {
11885

86+
/**
87+
* ### Definitions:
88+
* {@include [CellFormatterDef]}
89+
* {@include [LineBreak]}
90+
* {@include [RowColFormatterDef]}
91+
*
92+
* ### Notation:
93+
*
94+
* [**format**][DataFrame.format]**` { `**[`columns`][SelectingColumns]**` }`**
95+
*
96+
* {@include [Indent]}
97+
* `\[ `__`.`__[**`where`**][FormatClause.where]**` { `**[`filter`][SelectingRows.RowValueCondition]`: `[`RowValueFilter`][RowValueFilter]**` } `**`]`
98+
*
99+
* {@include [Indent]}
100+
* `\[ `__`.`__[**`at`**][FormatClause.at]**`(`**`rowIndices: `[Collection][Collection]`<`[Int][Int]`> | `[IntRange][IntRange]` | `**`vararg`**` `[Int][Int]**`)`**` ]`
101+
*
102+
* {@include [Indent]}
103+
* `\[ `__`.`__[**`notNull`**][FormatClause.notNull]**`()`**` ]`
104+
*
105+
* {@include [Indent]}
106+
* __`.`__[**`with`**][FormatClause.with]**` { `**{@include [CellFormatterRef]}**` }`**
107+
*
108+
* {@include [Indent]}
109+
* `| `__`.`__[**`notNull`**][FormatClause.notNull]**` { `**{@include [CellFormatterRef]}**` }`**
110+
*
111+
* {@include [Indent]}
112+
* `| `__`.`__[**`perRowCol`**][FormatClause.perRowCol]**` { `**{@include [RowColFormatterRef]}**` }`**
113+
*
114+
* {@include [Indent]}
115+
* `| `__`.`__[**`linearBg`**][FormatClause.linearBg]**`(`**`from: `[Pair][Pair]`<`[Number][Number]`, `[RgbColor][RgbColor]`>`**`,`**` to: `[Pair][Pair]`<`[Number][Number]`, `[RgbColor][RgbColor]`>`**`)`**
116+
*
117+
* `\[ `__`.`__[**format**][FormattedFrame.format]` ↺ \]`
118+
* {@include [LineBreak]}
119+
* {@include [FormattingDslGrammarDef]}
120+
*/
121+
@ExportAsHtml
122+
@ExcludeFromSources
123+
interface ForHtml
124+
119125
/**
120126
* ## Formatting DSL Grammar
121127
*

‎core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/api/format.kt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ internal inline fun <T, C> FormatClause<T, C>.formatImpl(
5656
val columns =
5757
if (clause.columns != null) {
5858
clause.df.getColumnsWithPaths(clause.columns)
59-
.mapNotNull { if (it.depth == 0) it.name else null }
59+
.mapNotNull { if (it.depth == 0) it.name else null } // TODO Causes #1356
6060
.toSet()
6161
} else {
6262
null

‎core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Modify.kt

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,16 @@
33
package org.jetbrains.kotlinx.dataframe.samples.api
44

55
import io.kotest.matchers.shouldBe
6+
import org.jetbrains.kotlinx.dataframe.DataColumn
67
import org.jetbrains.kotlinx.dataframe.DataFrame
78
import org.jetbrains.kotlinx.dataframe.DataRow
89
import org.jetbrains.kotlinx.dataframe.alsoDebug
910
import org.jetbrains.kotlinx.dataframe.annotations.DataSchema
11+
import org.jetbrains.kotlinx.dataframe.api.FormattingDsl
1012
import org.jetbrains.kotlinx.dataframe.api.ParserOptions
1113
import org.jetbrains.kotlinx.dataframe.api.add
1214
import org.jetbrains.kotlinx.dataframe.api.after
15+
import org.jetbrains.kotlinx.dataframe.api.and
1316
import org.jetbrains.kotlinx.dataframe.api.asColumn
1417
import org.jetbrains.kotlinx.dataframe.api.to
1518
import org.jetbrains.kotlinx.dataframe.api.asFrame
@@ -36,6 +39,7 @@ import org.jetbrains.kotlinx.dataframe.api.fillNaNs
3639
import org.jetbrains.kotlinx.dataframe.api.fillNulls
3740
import org.jetbrains.kotlinx.dataframe.api.filter
3841
import org.jetbrains.kotlinx.dataframe.api.flatten
42+
import org.jetbrains.kotlinx.dataframe.api.format
3943
import org.jetbrains.kotlinx.dataframe.api.gather
4044
import org.jetbrains.kotlinx.dataframe.api.getRows
4145
import org.jetbrains.kotlinx.dataframe.api.group
@@ -51,6 +55,7 @@ import org.jetbrains.kotlinx.dataframe.api.intoRows
5155
import org.jetbrains.kotlinx.dataframe.api.inward
5256
import org.jetbrains.kotlinx.dataframe.api.keysInto
5357
import org.jetbrains.kotlinx.dataframe.api.length
58+
import org.jetbrains.kotlinx.dataframe.api.linearBg
5459
import org.jetbrains.kotlinx.dataframe.api.lowercase
5560
import org.jetbrains.kotlinx.dataframe.api.map
5661
import org.jetbrains.kotlinx.dataframe.api.mapKeys
@@ -62,6 +67,7 @@ import org.jetbrains.kotlinx.dataframe.api.max
6267
import org.jetbrains.kotlinx.dataframe.api.mean
6368
import org.jetbrains.kotlinx.dataframe.api.meanFor
6469
import org.jetbrains.kotlinx.dataframe.api.merge
70+
import org.jetbrains.kotlinx.dataframe.api.min
6571
import org.jetbrains.kotlinx.dataframe.api.minus
6672
import org.jetbrains.kotlinx.dataframe.api.move
6773
import org.jetbrains.kotlinx.dataframe.api.named
@@ -1303,4 +1309,38 @@ class Modify : TestBase() {
13031309
}
13041310
// SampleEnd
13051311
}
1312+
1313+
@Test
1314+
fun formatExample_properties() {
1315+
// SampleStart
1316+
df
1317+
.format().with { bold and textColor(black) }
1318+
.format { isHappy }.with { background(if (it) green else red) }
1319+
.format { weight }.notNull().linearBg(50 to FormattingDsl.blue, 90 to FormattingDsl.red)
1320+
.format { age }.perRowCol { row, col ->
1321+
textColor(
1322+
linear(value = col[row], from = col.min() to blue, to = col.max() to green)
1323+
)
1324+
}
1325+
.toStandaloneHtml()
1326+
// SampleEnd
1327+
}
1328+
1329+
@Suppress("UNCHECKED_CAST")
1330+
@Test
1331+
fun formatExample_strings() {
1332+
// SampleStart
1333+
df
1334+
.format().with { bold and textColor(black) }
1335+
.format("isHappy").with { background(if (it as Boolean) green else red) }
1336+
.format("weight").notNull().with { linearBg(it as Int, 50 to blue, 90 to red) }
1337+
.format("age").perRowCol { row, col ->
1338+
col as DataColumn<Int>
1339+
textColor(
1340+
linear(value = col[row], from = col.min() to blue, to = col.max() to green)
1341+
)
1342+
}
1343+
.toStandaloneHtml()
1344+
// SampleEnd
1345+
}
13061346
}

0 commit comments

Comments
 (0)