Skip to content

Commit 660c2d7

Browse files
elizarovelizarov
authored
Use a separate Knit tool (Kotlin#1486)
* Use a separate Knit tool version 0.1.2 * Hierarchical knit.properties files are introduced which are gathered while walking up the directory tree with the properties in knit resources being top-level ones. * Freemarker templates for "knit.include" (top-level of example files) and "test.template" (test template) are introduced with locations that are resolved from properties. * KNIT and TEST_OUT directives are not supported anymore. - Knitting is controlled by "knit.dir" and "knit.pattern" props. - "test.name" prop or TEST_NAME directive drives test gen. * All markdown files are now clean of top-level knit-related boilerplate (only TEST_NAME directive is remaining in some) * All example files are renumbered. It affects example-basic-xx, which had the legacy numbering with later insertions. * All auto-generated files now have the correct source-file name specified at their beginning, due to consistent use of template substitution. * No need to customize knit.pattern anymore (works out-of-the box) * "knit.name" is automatically generated based on example's file name "example-basic-01" -> "exampleBasic01" * Not match-pattern-group woodoo anymore, "knit.pattern" cannot have any user-defined match groups. * No need to look for "package xxx" in knitted sources, as the example's package is always ${knit.package}.${knit.name} * Simpler test names: testKotlinxCoroutinesGuideBasic01 -> testExampleBasic01 * Replaced END_TOC with END directive * Build-scripts are improved: - Consistent code to use mavenLocal when snapshots versions are used. - Proper substitution logic to use Android AAR files so that Dokka has correct links to Google APIs. - Google repository is added to all projects.
1 parent 1ed6fcc commit 660c2d7

File tree

157 files changed

+914
-1662
lines changed

Some content is hidden

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

157 files changed

+914
-1662
lines changed

‎README.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -217,6 +217,12 @@ The `develop` branch is pushed to `master` during release.
217217

218218
* Full release procedure checklist is [here](RELEASE.md).
219219
* Steps for contributing new integration modules are explained [here](integration/README.md#Contributing).
220+
* Use [Knit](https://github.com/Kotlin/kotlinx-knit/blob/master/README.md) for updates to documentation:
221+
* In project root directory run `./gradlew knit`.
222+
* Commit updated documents and examples together with other changes.
223+
* Use [Binary Compatibility Validator](https://github.com/Kotlin/binary-compatibility-validator/blob/master/README.md) for updates to public API:
224+
* In project root directory run `./gradlew apiDump`.
225+
* Commit updated API index together with other changes.
220226

221227
<!--- MODULE kotlinx-coroutines-core -->
222228
<!--- INDEX kotlinx.coroutines -->

‎build.gradle

Lines changed: 28 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
2+
* Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
33
*/
44
import org.jetbrains.kotlin.konan.target.HostManager
55

@@ -9,7 +9,7 @@ def rootModule = "kotlinx.coroutines"
99
def coreModule = "kotlinx-coroutines-core"
1010
// Not applicable for Kotlin plugin
1111
def sourceless = ['kotlinx.coroutines', 'site', 'kotlinx-coroutines-bom']
12-
def internal = ['kotlinx.coroutines', 'site', 'benchmarks', 'knit', 'js-stub', 'stdlib-stubs']
12+
def internal = ['kotlinx.coroutines', 'site', 'benchmarks', 'js-stub', 'stdlib-stubs']
1313
// Not published
1414
def unpublished = internal + ['example-frontend-js', 'android-unit-tests']
1515

@@ -41,7 +41,16 @@ buildscript {
4141
}
4242
}
4343

44-
if (build_snapshot_train || atomicfu_version.endsWith("-SNAPSHOT")) {
44+
// Determine if any project dependency is using a snapshot version
45+
ext.using_snapshot_version = build_snapshot_train
46+
rootProject.properties.each { key, value ->
47+
if (key.endsWith("_version") && value instanceof String && value.endsWith("-SNAPSHOT")) {
48+
println("NOTE: USING SNAPSHOT VERSION: $key=$value")
49+
ext.using_snapshot_version=true
50+
}
51+
}
52+
53+
if (using_snapshot_version) {
4554
repositories {
4655
mavenLocal()
4756
maven { url "https://oss.sonatype.org/content/repositories/snapshots" }
@@ -67,6 +76,7 @@ buildscript {
6776
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
6877
classpath "org.jetbrains.dokka:dokka-gradle-plugin:$dokka_version"
6978
classpath "org.jetbrains.kotlinx:atomicfu-gradle-plugin:$atomicfu_version"
79+
classpath "org.jetbrains.kotlinx:kotlinx-knit:$knit_version"
7080
classpath "com.moowork.gradle:gradle-node-plugin:$gradle_node_version"
7181
classpath "org.jetbrains.kotlinx:binary-compatibility-validator:$binary_compatibility_validator_version"
7282

@@ -102,7 +112,7 @@ allprojects {
102112
kotlin_version = rootProject.properties['kotlin_snapshot_version']
103113
}
104114

105-
if (build_snapshot_train || atomicfu_version.endsWith("-SNAPSHOT") || lincheck_version.endsWith("-SNAPSHOT")) {
115+
if (using_snapshot_version) {
106116
repositories {
107117
mavenLocal()
108118
maven { url "https://oss.sonatype.org/content/repositories/snapshots" }
@@ -122,7 +132,7 @@ allprojects {
122132

123133
apply plugin: "binary-compatibility-validator"
124134
apiValidation {
125-
ignoredProjects += ["stdlib-stubs", "benchmarks", "knit", "site",
135+
ignoredProjects += ["stdlib-stubs", "benchmarks", "site",
126136
"kotlinx-coroutines-bom", "android-unit-tests", "js-stub"]
127137
ignoredPackages += "kotlinx.coroutines.internal"
128138
}
@@ -136,9 +146,7 @@ allprojects {
136146
* google should be first in the repository list because some of the play services
137147
* transitive dependencies was removed from jcenter, thus breaking gradle dependency resolution
138148
*/
139-
if (projectName == "kotlinx-coroutines-play-services") {
140-
google()
141-
}
149+
google()
142150
jcenter()
143151
maven {
144152
url "https://kotlin.bintray.com/kotlin-dev"
@@ -251,7 +259,7 @@ configure(subprojects.findAll { !unpublished.contains(it.name) }) {
251259
tasks.withType(dokka.getClass()) {
252260
externalDocumentationLink {
253261
url = new URL(core_docs_url)
254-
packageListUrl = new URL("file://$core_docs_file")
262+
packageListUrl = new File(core_docs_file).toURI().toURL()
255263
}
256264
}
257265
}
@@ -267,3 +275,14 @@ task deploy(dependsOn: getTasksByName("publish", true) + getTasksByName("publish
267275
apply plugin: 'base'
268276

269277
clean.dependsOn gradle.includedBuilds.collect { it.task(':clean') }
278+
279+
// --------------- Knit configuration ---------------
280+
281+
apply plugin: 'kotlinx-knit'
282+
283+
knit {
284+
siteRoot = "https://kotlin.github.io/kotlinx.coroutines"
285+
moduleRoots = [".", "integration", "reactive", "ui"]
286+
}
287+
288+
knitPrepare.dependsOn getTasksByName("dokka", true)

‎docs/basics.md

Lines changed: 9 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,4 @@
1-
<!--- INCLUDE .*/example-([a-z]+)-([0-9a-z]+)\.kt
2-
/*
3-
* Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
4-
*/
5-
6-
// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
7-
package kotlinx.coroutines.guide.$$1$$2
8-
-->
9-
<!--- KNIT ../kotlinx-coroutines-core/jvm/test/guide/.*\.kt -->
10-
<!--- TEST_OUT ../kotlinx-coroutines-core/jvm/test/guide/test/BasicsGuideTest.kt
11-
// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
12-
package kotlinx.coroutines.guide.test
13-
14-
import org.junit.Test
15-
16-
class BasicsGuideTest {
17-
-->
1+
<!--- TEST_NAME BasicsGuideTest -->
182

193
**Table of contents**
204

@@ -30,8 +14,7 @@ class BasicsGuideTest {
3014
* [Coroutines ARE light-weight](#coroutines-are-light-weight)
3115
* [Global coroutines are like daemon threads](#global-coroutines-are-like-daemon-threads)
3216

33-
<!--- END_TOC -->
34-
17+
<!--- END -->
3518

3619
## Coroutine Basics
3720

@@ -142,7 +125,7 @@ fun main() = runBlocking<Unit> { // start main coroutine
142125

143126
</div>
144127

145-
> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-02b.kt).
128+
> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-03.kt).
146129
147130
<!--- TEST
148131
Hello,
@@ -197,7 +180,7 @@ fun main() = runBlocking {
197180

198181
</div>
199182

200-
> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-03.kt).
183+
> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-04.kt).
201184
202185
<!--- TEST
203186
Hello,
@@ -242,7 +225,7 @@ fun main() = runBlocking { // this: CoroutineScope
242225

243226
</div>
244227

245-
> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-03s.kt).
228+
> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-05.kt).
246229
247230
<!--- TEST
248231
Hello,
@@ -288,7 +271,7 @@ fun main() = runBlocking { // this: CoroutineScope
288271

289272
</div>
290273

291-
> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-04.kt).
274+
> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-06.kt).
292275
293276
<!--- TEST
294277
Task from coroutine scope
@@ -327,7 +310,7 @@ suspend fun doWorld() {
327310

328311
</div>
329312

330-
> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-05.kt).
313+
> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-07.kt).
331314
332315
<!--- TEST
333316
Hello,
@@ -364,7 +347,7 @@ fun main() = runBlocking {
364347

365348
</div>
366349

367-
> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-06.kt).
350+
> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-08.kt).
368351
369352
<!--- TEST lines.size == 1 && lines[0] == ".".repeat(100_000) -->
370353

@@ -396,7 +379,7 @@ fun main() = runBlocking {
396379

397380
</div>
398381

399-
> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-07.kt).
382+
> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-09.kt).
400383
401384
You can run and see that it prints three lines and terminates:
402385

‎docs/cancellation-and-timeouts.md

Lines changed: 2 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,5 @@
1-
<!--- INCLUDE .*/example-([a-z]+)-([0-9a-z]+)\.kt
2-
/*
3-
* Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
4-
*/
1+
<!--- TEST_NAME CancellationGuideTest -->
52

6-
// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
7-
package kotlinx.coroutines.guide.$$1$$2
8-
-->
9-
<!--- KNIT ../kotlinx-coroutines-core/jvm/test/guide/.*\.kt -->
10-
<!--- TEST_OUT ../kotlinx-coroutines-core/jvm/test/guide/test/CancellationTimeOutsGuideTest.kt
11-
// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
12-
package kotlinx.coroutines.guide.test
13-
14-
import org.junit.Test
15-
16-
class CancellationTimeOutsGuideTest {
17-
-->
183
**Table of contents**
194

205
<!--- TOC -->
@@ -27,7 +12,7 @@ class CancellationTimeOutsGuideTest {
2712
* [Run non-cancellable block](#run-non-cancellable-block)
2813
* [Timeout](#timeout)
2914

30-
<!--- END_TOC -->
15+
<!--- END -->
3116

3217
## Cancellation and Timeouts
3318

‎docs/channels.md

Lines changed: 2 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,5 @@
1-
<!--- INCLUDE .*/example-([a-z]+)-([0-9a-z]+)\.kt
2-
/*
3-
* Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
4-
*/
1+
<!--- TEST_NAME ChannelsGuideTest -->
52

6-
// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
7-
package kotlinx.coroutines.guide.$$1$$2
8-
-->
9-
<!--- KNIT ../kotlinx-coroutines-core/jvm/test/guide/.*\.kt -->
10-
<!--- TEST_OUT ../kotlinx-coroutines-core/jvm/test/guide/test/ChannelsGuideTest.kt
11-
// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
12-
package kotlinx.coroutines.guide.test
13-
14-
import org.junit.Test
15-
16-
class ChannelsGuideTest {
17-
-->
183
**Table of contents**
194

205
<!--- TOC -->
@@ -31,7 +16,7 @@ class ChannelsGuideTest {
3116
* [Channels are fair](#channels-are-fair)
3217
* [Ticker channels](#ticker-channels)
3318

34-
<!--- END_TOC -->
19+
<!--- END -->
3520

3621
## Channels
3722

‎docs/compatibility.md

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,3 @@
1-
<!---
2-
/*
3-
* Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
4-
*/
5-
--->
6-
71
<!--- TOC -->
82

93
* [Compatibility](#compatibility)
@@ -19,7 +13,7 @@
1913
* [Gradle](#gradle)
2014
* [Maven](#maven)
2115

22-
<!--- END_TOC -->
16+
<!--- END -->
2317

2418
## Compatibility
2519
This document describes the compatibility policy of `kotlinx.coroutines` library since version 1.0.0 and semantics of compatibility-specific annotations.

‎docs/composing-suspending-functions.md

Lines changed: 2 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,4 @@
1-
<!--- INCLUDE .*/example-([a-z]+)-([0-9a-z]+)\.kt
2-
/*
3-
* Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
4-
*/
5-
6-
// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
7-
package kotlinx.coroutines.guide.$$1$$2
8-
-->
9-
<!--- KNIT ../kotlinx-coroutines-core/jvm/test/guide/.*\.kt -->
10-
<!--- TEST_OUT ../kotlinx-coroutines-core/jvm/test/guide/test/ComposingGuideTest.kt
11-
// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
12-
package kotlinx.coroutines.guide.test
13-
14-
import org.junit.Test
15-
16-
class ComposingGuideTest {
17-
-->
1+
<!--- TEST_NAME ComposingGuideTest -->
182

193
**Table of contents**
204

@@ -27,7 +11,7 @@ class ComposingGuideTest {
2711
* [Async-style functions](#async-style-functions)
2812
* [Structured concurrency with async](#structured-concurrency-with-async)
2913

30-
<!--- END_TOC -->
14+
<!--- END -->
3115

3216
## Composing Suspending Functions
3317

‎docs/coroutine-context-and-dispatchers.md

Lines changed: 2 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,4 @@
1-
<!--- INCLUDE .*/example-([a-z]+)-([0-9a-z]+)\.kt
2-
/*
3-
* Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
4-
*/
5-
6-
// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
7-
package kotlinx.coroutines.guide.$$1$$2
8-
-->
9-
<!--- KNIT ../kotlinx-coroutines-core/jvm/test/guide/.*\.kt -->
10-
<!--- TEST_OUT ../kotlinx-coroutines-core/jvm/test/guide/test/DispatcherGuideTest.kt
11-
// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
12-
package kotlinx.coroutines.guide.test
13-
14-
import org.junit.Test
15-
16-
class DispatchersGuideTest {
17-
-->
1+
<!--- TEST_NAME DispatcherGuideTest -->
182

193
**Table of contents**
204

@@ -33,7 +17,7 @@ class DispatchersGuideTest {
3317
* [Coroutine scope](#coroutine-scope)
3418
* [Thread-local data](#thread-local-data)
3519

36-
<!--- END_TOC -->
20+
<!--- END -->
3721

3822
## Coroutine Context and Dispatchers
3923

‎docs/debugging.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,7 @@
99
* [Debug agent](#debug-agent)
1010
* [Debug agent and Android](#debug-agent-and-android)
1111

12-
<!--- END_TOC -->
13-
12+
<!--- END -->
1413

1514
## Debugging coroutines
1615
Debugging asynchronous programs is challenging, because multiple concurrent coroutines are typically working at the same time.

‎docs/exception-handling.md

Lines changed: 2 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,5 @@
1-
<!--- INCLUDE .*/example-([a-z]+)-([0-9a-z]+)\.kt
2-
/*
3-
* Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
4-
*/
1+
<!--- TEST_NAME ExceptionsGuideTest -->
52

6-
// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
7-
package kotlinx.coroutines.guide.$$1$$2
8-
-->
9-
<!--- KNIT ../kotlinx-coroutines-core/jvm/test/guide/.*\.kt -->
10-
<!--- TEST_OUT ../kotlinx-coroutines-core/jvm/test/guide/test/ExceptionsGuideTest.kt
11-
// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
12-
package kotlinx.coroutines.guide.test
13-
14-
import org.junit.Test
15-
16-
class ExceptionsGuideTest {
17-
-->
183
**Table of contents**
194

205
<!--- TOC -->
@@ -29,7 +14,7 @@ class ExceptionsGuideTest {
2914
* [Supervision scope](#supervision-scope)
3015
* [Exceptions in supervised coroutines](#exceptions-in-supervised-coroutines)
3116

32-
<!--- END_TOC -->
17+
<!--- END -->
3318

3419
## Exception Handling
3520

@@ -260,7 +245,6 @@ to leak to its exception handler.
260245

261246

262247
<!--- INCLUDE
263-
264248
import kotlinx.coroutines.exceptions.*
265249
-->
266250

0 commit comments

Comments
 (0)