Skip to content

Commit ec5004b

Browse files
JolanrensenJolanrensen
authored
Merge pull request #308 from Kotlin/enable-kdocs-plugin
Enable Doc processor plugin
2 parents 62ab8a3 + ac3d738 commit ec5004b

File tree

272 files changed

+21188
-0
lines changed

Some content is hidden

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

272 files changed

+21188
-0
lines changed

‎build.gradle.kts

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ plugins {
1414
id("org.jetbrains.dokka") version libs.versions.dokka
1515
id("org.jetbrains.kotlinx.kover") version libs.versions.kover
1616
id("org.jmailen.kotlinter") version libs.versions.ktlint
17+
id("nl.jolanrensen.docProcessor") version libs.versions.docProcessor apply false
18+
id("xyz.ronella.simple-git") version libs.versions.simpleGit apply false
1719
}
1820

1921
val jupyterApiTCRepo: String by project

‎core/build.gradle.kts

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
import nl.jolanrensen.docProcessor.defaultProcessors.*
2+
import nl.jolanrensen.docProcessor.gradle.creatingProcessDocTask
3+
import org.gradle.jvm.tasks.Jar
4+
import xyz.ronella.gradle.plugin.simple.git.task.GitTask
5+
16
@Suppress("DSL_SCOPE_VIOLATION", "UnstableApiUsage")
27
plugins {
38
kotlin("jvm")
@@ -10,6 +15,9 @@ plugins {
1015
id("org.jetbrains.kotlinx.kover")
1116
id("org.jmailen.kotlinter")
1217
id("org.jetbrains.kotlinx.dataframe")
18+
id("nl.jolanrensen.docProcessor")
19+
id("xyz.ronella.simple-git")
20+
idea
1321
}
1422

1523
group = "org.jetbrains.kotlinx"
@@ -52,6 +60,66 @@ kotlin.sourceSets {
5260
}
5361
}
5462

63+
val generatedSourcesFolderName = "generated-sources"
64+
val addGeneratedSourcesToGit by tasks.creating(GitTask::class) {
65+
directory.set(file("."))
66+
command.set("add")
67+
args.set(listOf("-A", generatedSourcesFolderName))
68+
}
69+
70+
// Backup the kotlin source files location
71+
val kotlinMainSources = kotlin.sourceSets.main.get().kotlin.sourceDirectories
72+
73+
// Task to generate the processed documentation
74+
val processKDocsMain by creatingProcessDocTask(
75+
sources = kotlinMainSources.filterNot { "build/generated" in it.path }, // Exclude generated sources
76+
) {
77+
target = file(generatedSourcesFolderName)
78+
processors = listOf(
79+
INCLUDE_DOC_PROCESSOR,
80+
INCLUDE_FILE_DOC_PROCESSOR,
81+
INCLUDE_ARG_DOC_PROCESSOR,
82+
COMMENT_DOC_PROCESSOR,
83+
SAMPLE_DOC_PROCESSOR,
84+
)
85+
86+
task {
87+
doLast {
88+
// ensure generated sources are added to git
89+
addGeneratedSourcesToGit.executeCommand()
90+
}
91+
}
92+
}
93+
94+
// Exclude the generated/processed sources from the IDE
95+
idea {
96+
module {
97+
excludeDirs.add(file(generatedSourcesFolderName))
98+
}
99+
}
100+
101+
// Modify all Jar tasks such that before running the Kotlin sources are set to
102+
// the target of processKdocMain and they are returned back to normal afterwards.
103+
tasks.withType<Jar> {
104+
dependsOn(processKDocsMain)
105+
outputs.upToDateWhen { false }
106+
107+
doFirst {
108+
kotlin.sourceSets.main {
109+
kotlin.setSrcDirs(
110+
processKDocsMain.targets +
111+
kotlinMainSources.filter { "build/generated" in it.path } // Include generated sources (which were excluded above)
112+
)
113+
}
114+
}
115+
116+
doLast {
117+
kotlin.sourceSets.main {
118+
kotlin.setSrcDirs(kotlinMainSources)
119+
}
120+
}
121+
}
122+
55123
korro {
56124
docs = fileTree(rootProject.rootDir) {
57125
include("docs/StardustDocs/topics/*.md")
@@ -169,3 +237,13 @@ dataframes {
169237
name = "org.jetbrains.kotlinx.dataframe.samples.api.Repository"
170238
}
171239
}
240+
241+
// If we want to use Dokka, make sure to use the preprocessed sources
242+
tasks.withType<org.jetbrains.dokka.gradle.AbstractDokkaLeafTask> {
243+
dependsOn(processKDocsMain)
244+
dokkaSourceSets {
245+
all {
246+
sourceRoot(processKDocsMain.target.get())
247+
}
248+
}
249+
}

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

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
package org.jetbrains.kotlinx.dataframe
2+
3+
import org.jetbrains.kotlinx.dataframe.api.ColumnSelectionDsl
4+
import org.jetbrains.kotlinx.dataframe.api.asColumnGroup
5+
import org.jetbrains.kotlinx.dataframe.api.cast
6+
import org.jetbrains.kotlinx.dataframe.api.castFrameColumn
7+
import org.jetbrains.kotlinx.dataframe.api.getColumn
8+
import org.jetbrains.kotlinx.dataframe.columns.ColumnGroup
9+
import org.jetbrains.kotlinx.dataframe.columns.ColumnPath
10+
import org.jetbrains.kotlinx.dataframe.columns.ColumnReference
11+
import org.jetbrains.kotlinx.dataframe.columns.FrameColumn
12+
import org.jetbrains.kotlinx.dataframe.impl.columnName
13+
import org.jetbrains.kotlinx.dataframe.impl.columns.asAnyFrameColumn
14+
import kotlin.reflect.KProperty
15+
16+
/**
17+
* Provides access to [columns][DataColumn].
18+
*
19+
* Base interface for [DataFrame] and [ColumnSelectionDsl]
20+
*
21+
* @param T Schema marker. Used to generate extension properties for typed column access.
22+
*/
23+
public interface ColumnsContainer<out T> {
24+
25+
// region columns
26+
27+
public fun columns(): List<AnyCol>
28+
public fun columnsCount(): Int
29+
public fun containsColumn(name: String): Boolean
30+
public fun containsColumn(path: ColumnPath): Boolean
31+
public fun getColumnIndex(name: String): Int
32+
33+
// endregion
34+
35+
// region getColumnOrNull
36+
37+
public fun getColumnOrNull(name: String): AnyCol?
38+
public fun getColumnOrNull(index: Int): AnyCol?
39+
public fun <R> getColumnOrNull(column: ColumnReference<R>): DataColumn<R>?
40+
public fun getColumnOrNull(path: ColumnPath): AnyCol?
41+
public fun <R> getColumnOrNull(column: ColumnSelector<T, R>): DataColumn<R>?
42+
43+
// endregion
44+
45+
// region get
46+
47+
public operator fun get(columnName: String): AnyCol = getColumn(columnName)
48+
public operator fun get(columnPath: ColumnPath): AnyCol = getColumn(columnPath)
49+
50+
public operator fun <R> get(column: DataColumn<R>): DataColumn<R> = getColumn(column.name()).cast()
51+
public operator fun <R> get(column: DataColumn<DataRow<R>>): ColumnGroup<R> = getColumn(column)
52+
public operator fun <R> get(column: DataColumn<DataFrame<R>>): FrameColumn<R> = getColumn(column)
53+
54+
public operator fun <R> get(column: ColumnReference<R>): DataColumn<R> = getColumn(column)
55+
public operator fun <R> get(column: ColumnReference<DataRow<R>>): ColumnGroup<R> = getColumn(column)
56+
public operator fun <R> get(column: ColumnReference<DataFrame<R>>): FrameColumn<R> = getColumn(column)
57+
58+
public operator fun <R> get(column: KProperty<R>): DataColumn<R> = get(column.columnName).cast()
59+
public operator fun <R> get(column: KProperty<DataRow<R>>): ColumnGroup<R> = get(column.columnName).asColumnGroup().cast()
60+
public operator fun <R> get(column: KProperty<DataFrame<R>>): FrameColumn<R> = get(column.columnName).asAnyFrameColumn().castFrameColumn()
61+
62+
public operator fun <C> get(columns: ColumnsSelector<T, C>): List<DataColumn<C>>
63+
public operator fun <C> get(column: ColumnSelector<T, C>): DataColumn<C> = get(column as ColumnsSelector<T, C>).single()
64+
65+
// endregion
66+
}

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

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
package org.jetbrains.kotlinx.dataframe
2+
3+
import org.jetbrains.kotlinx.dataframe.api.Infer
4+
import org.jetbrains.kotlinx.dataframe.api.asDataColumn
5+
import org.jetbrains.kotlinx.dataframe.api.cast
6+
import org.jetbrains.kotlinx.dataframe.api.concat
7+
import org.jetbrains.kotlinx.dataframe.api.filter
8+
import org.jetbrains.kotlinx.dataframe.api.schema
9+
import org.jetbrains.kotlinx.dataframe.api.take
10+
import org.jetbrains.kotlinx.dataframe.columns.BaseColumn
11+
import org.jetbrains.kotlinx.dataframe.columns.ColumnGroup
12+
import org.jetbrains.kotlinx.dataframe.columns.ColumnKind
13+
import org.jetbrains.kotlinx.dataframe.columns.ColumnPath
14+
import org.jetbrains.kotlinx.dataframe.columns.ColumnResolutionContext
15+
import org.jetbrains.kotlinx.dataframe.columns.ColumnWithPath
16+
import org.jetbrains.kotlinx.dataframe.columns.FrameColumn
17+
import org.jetbrains.kotlinx.dataframe.columns.ValueColumn
18+
import org.jetbrains.kotlinx.dataframe.impl.columns.ColumnGroupImpl
19+
import org.jetbrains.kotlinx.dataframe.impl.columns.FrameColumnImpl
20+
import org.jetbrains.kotlinx.dataframe.impl.columns.ValueColumnImpl
21+
import org.jetbrains.kotlinx.dataframe.impl.columns.addPath
22+
import org.jetbrains.kotlinx.dataframe.impl.columns.guessColumnType
23+
import org.jetbrains.kotlinx.dataframe.impl.columns.toColumnKind
24+
import org.jetbrains.kotlinx.dataframe.impl.getValuesType
25+
import org.jetbrains.kotlinx.dataframe.impl.splitByIndices
26+
import org.jetbrains.kotlinx.dataframe.schema.DataFrameSchema
27+
import kotlin.reflect.KClass
28+
import kotlin.reflect.KProperty
29+
import kotlin.reflect.KType
30+
import kotlin.reflect.typeOf
31+
32+
/**
33+
* Column with [name] and [values] of specific [type].
34+
*
35+
* Base interface for [ValueColumn] and [FrameColumn], but not for [ColumnGroup]. However, implementations for all three [column kinds][ColumnKind] derive from DataColumn and can cast to it safely.
36+
* Column operations that have signature clash with [DataFrame] API ([filter], [take], [map] etc.) are defined for [DataColumn] and not for [BaseColumn].
37+
*
38+
* @param T type of values in the column.
39+
*/
40+
public interface DataColumn<out T> : BaseColumn<T> {
41+
42+
public companion object {
43+
44+
/**
45+
* Creates [ValueColumn] using given [name], [values] and [type].
46+
*
47+
* @param name name of the column
48+
* @param values list of column values
49+
* @param type type of the column
50+
* @param infer column type inference mode
51+
*/
52+
public fun <T> createValueColumn(
53+
name: String,
54+
values: List<T>,
55+
type: KType,
56+
infer: Infer = Infer.None,
57+
defaultValue: T? = null
58+
): ValueColumn<T> = ValueColumnImpl(values, name, getValuesType(values, type, infer), defaultValue)
59+
60+
/**
61+
* Creates [ValueColumn] using given [name], [values] and reified column [type].
62+
*
63+
* Note, that column [type] will be defined at compile-time using [T] argument
64+
*
65+
* @param T type of the column
66+
* @param name name of the column
67+
* @param values list of column values
68+
* @param infer column type inference mode
69+
*/
70+
public inline fun <reified T> createValueColumn(name: String, values: List<T>, infer: Infer = Infer.None): ValueColumn<T> = createValueColumn(
71+
name, values,
72+
getValuesType(
73+
values,
74+
typeOf<T>(),
75+
infer
76+
)
77+
)
78+
79+
public fun <T> createColumnGroup(name: String, df: DataFrame<T>): ColumnGroup<T> = ColumnGroupImpl(name, df)
80+
81+
public fun <T> createFrameColumn(
82+
name: String,
83+
df: DataFrame<T>,
84+
startIndices: Iterable<Int>
85+
): FrameColumn<T> =
86+
FrameColumnImpl(name, df.splitByIndices(startIndices.asSequence()).toList(), lazy { df.schema() })
87+
88+
public fun <T> createFrameColumn(
89+
name: String,
90+
groups: List<DataFrame<T>>,
91+
schema: Lazy<DataFrameSchema>? = null
92+
): FrameColumn<T> = FrameColumnImpl(name, groups, schema)
93+
94+
public fun <T> createWithTypeInference(name: String, values: List<T>, nullable: Boolean? = null): DataColumn<T> = guessColumnType(name, values, nullable = nullable)
95+
96+
public fun <T> create(name: String, values: List<T>, type: KType, infer: Infer = Infer.None): DataColumn<T> {
97+
return when (type.toColumnKind()) {
98+
ColumnKind.Value -> createValueColumn(name, values, type, infer)
99+
ColumnKind.Group -> createColumnGroup(name, (values as List<AnyRow?>).concat()).asDataColumn().cast()
100+
ColumnKind.Frame -> createFrameColumn(name, values as List<AnyFrame>).asDataColumn().cast()
101+
}
102+
}
103+
104+
public inline fun <reified T> create(name: String, values: List<T>, infer: Infer = Infer.None): DataColumn<T> = create(name, values, typeOf<T>(), infer)
105+
106+
public fun empty(name: String = ""): AnyCol = createValueColumn(name, emptyList<Unit>(), typeOf<Unit>())
107+
}
108+
109+
public fun hasNulls(): Boolean = type().isMarkedNullable
110+
111+
override fun distinct(): DataColumn<T>
112+
113+
override fun get(indices: Iterable<Int>): DataColumn<T>
114+
115+
override fun rename(newName: String): DataColumn<T>
116+
117+
override fun resolveSingle(context: ColumnResolutionContext): ColumnWithPath<T>? = this.addPath()
118+
119+
override operator fun getValue(thisRef: Any?, property: KProperty<*>): DataColumn<T> = super.getValue(thisRef, property) as DataColumn<T>
120+
121+
public operator fun iterator(): Iterator<T> = values().iterator()
122+
123+
public override operator fun get(range: IntRange): DataColumn<T>
124+
}
125+
126+
public val AnyCol.name: String get() = name()
127+
public val AnyCol.path: ColumnPath get() = path()
128+
129+
public val <T> DataColumn<T>.values: Iterable<T> get() = values()
130+
public val AnyCol.hasNulls: Boolean get() = hasNulls()
131+
public val AnyCol.size: Int get() = size()
132+
public val AnyCol.indices: IntRange get() = indices()
133+
134+
public val AnyCol.type: KType get() = type()
135+
public val AnyCol.kind: ColumnKind get() = kind()
136+
public val AnyCol.typeClass: KClass<*> get() = type.classifier as? KClass<*> ?: error("Cannot cast ${type.classifier?.javaClass} to a ${KClass::class}. Column $name: $type")
137+
138+
public fun AnyBaseCol.indices(): IntRange = 0 until size()

0 commit comments

Comments
 (0)