Skip to content

Commit e7e2ad1

Browse files
elizarovelizarov
committed
Simplified references to documentation from markdown files
1 parent fdcc719 commit e7e2ad1

File tree

14 files changed

+105
-72
lines changed

14 files changed

+105
-72
lines changed

‎coroutines-guide.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2182,8 +2182,7 @@ Channel was closed
21822182
* [Coroutines design document (KEEP)](https://github.com/Kotlin/kotlin-coroutines/blob/master/kotlin-coroutines-informal.md)
21832183
* [Full kotlinx.coroutines API reference](http://kotlin.github.io/kotlinx.coroutines)
21842184

2185-
<!--- SITE_ROOT https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core -->
2186-
<!--- DOCS_ROOT kotlinx-coroutines-core/target/dokka/kotlinx-coroutines-core -->
2185+
<!--- MODULE kotlinx-coroutines-core -->
21872186
<!--- INDEX kotlinx.coroutines.experimental -->
21882187
[launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/launch.html
21892188
[delay]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/delay.html

‎integration/kotlinx-coroutines-guava/README.md

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -48,12 +48,10 @@ that makes it especially bad choice for coroutine-based Kotlin code.
4848

4949
Integration with Guava [ListenableFuture](https://github.com/google/guava/wiki/ListenableFutureExplained).
5050

51-
<!--- SITE_ROOT https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core -->
52-
<!--- DOCS_ROOT kotlinx-coroutines-core/target/dokka/kotlinx-coroutines-core -->
51+
<!--- MODULE kotlinx-coroutines-core -->
5352
<!--- INDEX kotlinx.coroutines.experimental -->
5453
[CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-scope/index.html
55-
<!--- SITE_ROOT https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-guava -->
56-
<!--- DOCS_ROOT integration/kotlinx-coroutines-guava/target/dokka/kotlinx-coroutines-guava -->
54+
<!--- MODULE kotlinx-coroutines-guava -->
5755
<!--- INDEX kotlinx.coroutines.experimental.guava -->
5856
[future]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-guava/kotlinx.coroutines.experimental.guava/future.html
5957
[com.google.common.util.concurrent.ListenableFuture]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-guava/kotlinx.coroutines.experimental.guava/com.google.common.util.concurrent.-listenable-future/index.html

‎integration/kotlinx-coroutines-jdk8/README.md

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -49,12 +49,10 @@ that makes it especially bad choice for coroutine-based Kotlin code.
4949

5050
Additional libraries for JDK8 [CompletableFuture][java.util.concurrent.CompletableFuture].
5151

52-
<!--- SITE_ROOT https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core -->
53-
<!--- DOCS_ROOT kotlinx-coroutines-core/target/dokka/kotlinx-coroutines-core -->
52+
<!--- MODULE kotlinx-coroutines-core -->
5453
<!--- INDEX kotlinx.coroutines.experimental -->
5554
[CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-scope/index.html
56-
<!--- SITE_ROOT https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-jdk8 -->
57-
<!--- DOCS_ROOT integration/kotlinx-coroutines-jdk8/target/dokka/kotlinx-coroutines-jdk8 -->
55+
<!--- MODULE kotlinx-coroutines-jdk8 -->
5856
<!--- INDEX kotlinx.coroutines.experimental.future -->
5957
[future]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.experimental.future/future.html
6058
[java.util.concurrent.CompletableFuture]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.experimental.future/java.util.concurrent.-completable-future/index.html

‎knit/pom.xml

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,11 @@
2929

3030
<build>
3131
<sourceDirectory>src</sourceDirectory>
32-
<testSourceDirectory>test</testSourceDirectory>
33-
32+
<resources>
33+
<resource>
34+
<directory>resources</directory>
35+
</resource>
36+
</resources>
3437
<plugins>
3538
<!-- skip dokka for this module -->
3639
<plugin>

‎knit/resources/knit.properties

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
#
2+
# Copyright 2016-2017 JetBrains s.r.o.
3+
#
4+
# Licensed under the Apache License, Version 2.0 (the "License");
5+
# you may not use this file except in compliance with the License.
6+
# You may obtain a copy of the License at
7+
#
8+
# http://www.apache.org/licenses/LICENSE-2.0
9+
#
10+
# Unless required by applicable law or agreed to in writing, software
11+
# distributed under the License is distributed on an "AS IS" BASIS,
12+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
# See the License for the specific language governing permissions and
14+
# limitations under the License.
15+
#
16+
17+
site.root=https://kotlin.github.io/kotlinx.coroutines
18+
19+
module.roots=. integration reactive ui
20+
module.marker=pom.xml
21+
module.docs=target/dokka

‎knit/src/Knit.kt

Lines changed: 48 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,24 @@
1414
* limitations under the License.
1515
*/
1616

17-
import java.io.*
17+
import java.io.File
18+
import java.io.IOException
19+
import java.io.LineNumberReader
20+
import java.io.Reader
21+
import java.util.*
22+
import kotlin.properties.Delegates
23+
24+
// --- props in knit.properties
25+
26+
val knitProperties = ClassLoader.getSystemClassLoader()
27+
.getResource("knit.properties").openStream().use { Properties().apply { load(it) } }
28+
29+
val siteRoot = knitProperties.getProperty("site.root")!!
30+
val moduleRoots = knitProperties.getProperty("module.roots").split(" ")
31+
val moduleMarker = knitProperties.getProperty("module.marker")!!
32+
val moduleDocs = knitProperties.getProperty("module.docs")!!
33+
34+
// --- markdown syntax
1835

1936
const val DIRECTIVE_START = "<!--- "
2037
const val DIRECTIVE_END = "-->"
@@ -27,8 +44,7 @@ const val TEST_DIRECTIVE = "TEST"
2744

2845
const val TEST_OUT_DIRECTIVE = "TEST_OUT"
2946

30-
const val SITE_ROOT_DIRECTIVE = "SITE_ROOT"
31-
const val DOCS_ROOT_DIRECTIVE = "DOCS_ROOT"
47+
const val MODULE_DIRECTIVE = "MODULE"
3248
const val INDEX_DIRECTIVE = "INDEX"
3349

3450
const val CODE_START = "```kotlin"
@@ -54,10 +70,12 @@ fun main(args: Array<String>) {
5470
println("Usage: Knit <markdown-files>")
5571
return
5672
}
57-
args.forEach(::knit)
73+
args.forEach {
74+
if (!knit(it)) System.exit(1) // abort on first error with error exit code
75+
}
5876
}
5977

60-
fun knit(markdownFileName: String) {
78+
fun knit(markdownFileName: String): Boolean {
6179
println("*** Reading $markdownFileName")
6280
val markdownFile = File(markdownFileName)
6381
val tocLines = arrayListOf<String>()
@@ -71,8 +89,8 @@ fun knit(markdownFileName: String) {
7189
val files = mutableSetOf<File>()
7290
val allApiRefs = arrayListOf<ApiRef>()
7391
val remainingApiRefNames = mutableSetOf<String>()
74-
var siteRoot: String? = null
75-
var docsRoot: String? = null
92+
var moduleName: String by Delegates.notNull()
93+
var docsRoot: String by Delegates.notNull()
7694
// read markdown file
7795
var putBackLine: String? = null
7896
val markdown = markdownFile.withMarkdownTextReader {
@@ -129,7 +147,7 @@ fun knit(markdownFileName: String) {
129147
TEST_DIRECTIVE -> {
130148
require(lastPgk != null) { "'$PACKAGE_PREFIX' prefix was not found in emitted code"}
131149
require(testOut != null) { "$TEST_OUT_DIRECTIVE directive was not specified" }
132-
var predicate = directive.param
150+
val predicate = directive.param
133151
if (testLines.isEmpty()) {
134152
if (directive.singleLine) {
135153
require(!predicate.isEmpty()) { "$TEST_OUT_DIRECTIVE must be preceded by $TEST_START block or contain test predicate"}
@@ -141,19 +159,15 @@ fun knit(markdownFileName: String) {
141159
makeTest(testOutLines, lastPgk!!, testLines, predicate)
142160
testLines.clear()
143161
}
144-
SITE_ROOT_DIRECTIVE -> {
162+
MODULE_DIRECTIVE -> {
145163
requireSingleLine(directive)
146-
siteRoot = directive.param
147-
}
148-
DOCS_ROOT_DIRECTIVE -> {
149-
requireSingleLine(directive)
150-
docsRoot = directive.param
164+
moduleName = directive.param
165+
docsRoot = findModuleRootDir(moduleName) + "/" + moduleDocs + "/" + moduleName
151166
}
152167
INDEX_DIRECTIVE -> {
153168
requireSingleLine(directive)
154-
require(siteRoot != null) { "$SITE_ROOT_DIRECTIVE must be specified" }
155-
require(docsRoot != null) { "$DOCS_ROOT_DIRECTIVE must be specified" }
156-
val indexLines = processApiIndex(siteRoot!!, docsRoot!!, directive.param, remainingApiRefNames)
169+
val indexLines = processApiIndex(siteRoot + "/" + moduleName, docsRoot, directive.param, remainingApiRefNames)
170+
?: throw IllegalArgumentException("Failed to load index for ${directive.param}")
157171
skip = true
158172
while (true) {
159173
val skipLine = readLine() ?: break@mainLoop
@@ -210,7 +224,7 @@ fun knit(markdownFileName: String) {
210224
writeLinesIfNeeded(file, outLines)
211225
}
212226
}
213-
}
227+
} ?: return false // false when failed
214228
// update markdown file with toc
215229
val newLines = buildList<String> {
216230
addAll(markdown.preTocText)
@@ -230,6 +244,7 @@ fun knit(markdownFileName: String) {
230244
}
231245
// write test output
232246
flushTestOut(markdownFile.parentFile, testOut, testOutLines)
247+
return true
233248
}
234249

235250
fun makeTest(testOutLines: MutableList<String>, pgk: String, test: List<String>, predicate: String) {
@@ -360,19 +375,20 @@ class MarkdownTextReader(r: Reader) : LineNumberReader(r) {
360375
}
361376
}
362377

363-
fun <T : LineNumberReader> File.withLineNumberReader(factory: (Reader) -> T, block: T.() -> Unit): T {
378+
fun <T : LineNumberReader> File.withLineNumberReader(factory: (Reader) -> T, block: T.() -> Unit): T? {
364379
val reader = factory(reader())
365380
reader.use {
366381
try {
367382
it.block()
368-
} catch (e: IllegalArgumentException) {
383+
} catch (e: Exception) {
369384
println("ERROR: ${this@withLineNumberReader}: ${it.lineNumber}: ${e.message}")
385+
return null
370386
}
371387
}
372388
return reader
373389
}
374390

375-
fun File.withMarkdownTextReader(block: MarkdownTextReader.() -> Unit): MarkdownTextReader =
391+
fun File.withMarkdownTextReader(block: MarkdownTextReader.() -> Unit): MarkdownTextReader? =
376392
withLineNumberReader<MarkdownTextReader>(::MarkdownTextReader, block)
377393

378394
fun writeLinesIfNeeded(file: File, outLines: List<String>) {
@@ -392,6 +408,12 @@ fun writeLines(file: File, lines: List<String>) {
392408
}
393409
}
394410

411+
fun findModuleRootDir(name: String): String =
412+
moduleRoots
413+
.map { it + "/" + name }
414+
.firstOrNull { File(it + "/" + moduleMarker).exists() }
415+
?: throw IllegalArgumentException("Module $name is not found in any of the module root dirs")
416+
395417
data class ApiIndexKey(
396418
val docsRoot: String,
397419
val pkg: String
@@ -408,7 +430,7 @@ fun loadApiIndex(
408430
path: String,
409431
pkg: String,
410432
namePrefix: String = ""
411-
): Map<String, String> {
433+
): Map<String, String>? {
412434
val fileName = docsRoot + "/" + path + INDEX_MD
413435
val visited = mutableSetOf<String>()
414436
val map = HashMap<String,String>()
@@ -425,10 +447,11 @@ fun loadApiIndex(
425447
if (visited.add(refLink)) {
426448
val path2 = path + "/" + refLink.substring(0, refLink.length - INDEX_HTML.length)
427449
map += loadApiIndex(docsRoot, path2, pkg, refName + ".")
450+
?: throw IllegalArgumentException("Failed to parse ${docsRoot + "/" + path2}")
428451
}
429452
}
430453
}
431-
}
454+
} ?: return null // return null on failure
432455
return map
433456
}
434457

@@ -437,11 +460,11 @@ fun processApiIndex(
437460
docsRoot: String,
438461
pkg: String,
439462
remainingApiRefNames: MutableSet<String>
440-
): List<String> {
463+
): List<String>? {
441464
val key = ApiIndexKey(docsRoot, pkg)
442465
val map = apiIndexCache.getOrPut(key, {
443466
print("Parsing API docs at $docsRoot/$pkg: ")
444-
val result = loadApiIndex(docsRoot, pkg, pkg)
467+
val result = loadApiIndex(docsRoot, pkg, pkg) ?: return null // null on failure
445468
println("${result.size} definitions")
446469
result
447470
})

‎kotlinx-coroutines-core/README.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -75,8 +75,7 @@ Channels -- non-blocking primitives for communicating a stream of elements betwe
7575

7676
Select expression to perform multiple suspending operations simultaneously until one of them succeeds.
7777

78-
<!--- SITE_ROOT https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core -->
79-
<!--- DOCS_ROOT kotlinx-coroutines-core/target/dokka/kotlinx-coroutines-core -->
78+
<!--- MODULE kotlinx-coroutines-core -->
8079
<!--- INDEX kotlinx.coroutines.experimental -->
8180
[launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/launch.html
8281
[Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/index.html

‎reactive/coroutines-guide-reactive.md

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1044,8 +1044,7 @@ of work and you have to combine many operators for a complex processing. However
10441044
where you can have an arbitrary complex processing in a coroutine. Usually, you only need to chain stream-processing
10451045
coroutines for complex pipelines with fan-in and fan-out between multiple worker coroutines.
10461046

1047-
<!--- SITE_ROOT https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core -->
1048-
<!--- DOCS_ROOT kotlinx-coroutines-core/target/dokka/kotlinx-coroutines-core -->
1047+
<!--- MODULE kotlinx-coroutines-core -->
10491048
<!--- INDEX kotlinx.coroutines.experimental -->
10501049
[runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/run-blocking.html
10511050
[Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-unconfined/index.html
@@ -1068,14 +1067,12 @@ coroutines for complex pipelines with fan-in and fan-out between multiple worker
10681067
<!--- INDEX kotlinx.coroutines.experimental.selects -->
10691068
[select]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.selects/select.html
10701069
[whileSelect]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.selects/while-select.html
1071-
<!--- SITE_ROOT https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive -->
1072-
<!--- DOCS_ROOT reactive/kotlinx-coroutines-reactive/target/dokka/kotlinx-coroutines-reactive -->
1070+
<!--- MODULE kotlinx-coroutines-reactive -->
10731071
<!--- INDEX kotlinx.coroutines.experimental.reactive -->
10741072
[publish]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.experimental.reactive/publish.html
10751073
[org.reactivestreams.Publisher.consumeEach]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.experimental.reactive/org.reactivestreams.-publisher/consume-each.html
10761074
[org.reactivestreams.Publisher.open]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.experimental.reactive/org.reactivestreams.-publisher/open.html
1077-
<!--- SITE_ROOT https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-rx2 -->
1078-
<!--- DOCS_ROOT reactive/kotlinx-coroutines-rx2/target/dokka/kotlinx-coroutines-rx2 -->
1075+
<!--- MODULE kotlinx-coroutines-rx2 -->
10791076
<!--- INDEX kotlinx.coroutines.experimental.rx2 -->
10801077
[rxFlowable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-rx2/kotlinx.coroutines.experimental.rx2/rx-flowable.html
10811078
<!--- END -->

‎reactive/kotlinx-coroutines-reactive/README.md

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,15 +25,13 @@ Conversion functions:
2525
| -------- | ---------------
2626
| [ReceiveChannel.asPublisher][kotlinx.coroutines.experimental.channels.ReceiveChannel.asPublisher] | Converts streaming channel to hot publisher
2727

28-
<!--- SITE_ROOT https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core -->
29-
<!--- DOCS_ROOT kotlinx-coroutines-core/target/dokka/kotlinx-coroutines-core -->
28+
<!--- MODULE kotlinx-coroutines-core -->
3029
<!--- INDEX kotlinx.coroutines.experimental -->
3130
<!--- INDEX kotlinx.coroutines.experimental.channels -->
3231
[ProducerScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-producer-scope/index.html
3332
[ReceiveChannel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-receive-channel/index.html
3433
[ChannelIterator]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-channel-iterator/index.html
35-
<!--- SITE_ROOT https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive -->
36-
<!--- DOCS_ROOT reactive/kotlinx-coroutines-reactive/target/dokka/kotlinx-coroutines-reactive -->
34+
<!--- MODULE kotlinx-coroutines-reactive -->
3735
<!--- INDEX kotlinx.coroutines.experimental.reactive -->
3836
[publish]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.experimental.reactive/publish.html
3937
[org.reactivestreams.Publisher.awaitFirst]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactive/kotlinx.coroutines.experimental.reactive/org.reactivestreams.-publisher/await-first.html

‎reactive/kotlinx-coroutines-reactor/README.md

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,15 +23,13 @@ Conversion functions:
2323
| [Scheduler.asCoroutineDispatcher][reactor.core.scheduler.Scheduler.asCoroutineDispatcher] | Converts scheduler to [CoroutineDispatcher]
2424
| [TimedScheduler.asCoroutineDispatcher][reactor.core.scheduler.TimedScheduler.asCoroutineDispatcher] | Converts scheduler to [CoroutineDispatcher] supporting [Delay]
2525

26-
<!--- SITE_ROOT https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core -->
27-
<!--- DOCS_ROOT kotlinx-coroutines-core/target/dokka/kotlinx-coroutines-core -->
26+
<!--- MODULE kotlinx-coroutines-core -->
2827
<!--- INDEX kotlinx.coroutines.experimental -->
2928
[CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-scope/index.html
3029
[CoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-dispatcher/index.html
3130
[Delay]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-delay/index.html
3231
<!--- INDEX kotlinx.coroutines.experimental.channels -->
33-
<!--- SITE_ROOT https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactor -->
34-
<!--- DOCS_ROOT reactive/kotlinx-coroutines-reactor/target/dokka/kotlinx-coroutines-reactor -->
32+
<!--- MODULE kotlinx-coroutines-reactor -->
3533
<!--- INDEX kotlinx.coroutines.experimental.reactor -->
3634
[mono]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactor/kotlinx.coroutines.experimental.reactor/mono.html
3735
[flux]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-reactor/kotlinx.coroutines.experimental.reactor/flux.html

0 commit comments

Comments
 (0)