update: update docs for the new WebHelp engine

CHANGES.md

@@ -237,12 +237,12 @@ Gradle version 5.3 or later to use this version of kotlinx.coroutines in your Ko
 This version is the first stable release with [`Flow`](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html) API.
 
 All `Flow` API not marked with `@FlowPreview` or `@ExperimentalCoroutinesApi` annotations are stable and here to stay.
-Flow declarations marked with `@ExperimentalCoroutinesApi` have [the same guarantees](/docs/compatibility.md#experimental-api) as regular experimental API.
-Please note that API marked with `@FlowPreview` have [weak guarantees](/docs/compatibility.md#flow-preview-api) on source, binary and semantic compatibility.
+Flow declarations marked with `@ExperimentalCoroutinesApi` have [the same guarantees](/docs/topics/compatibility.md#experimental-api) as regular experimental API.
+Please note that API marked with `@FlowPreview` have [weak guarantees](/docs/topics/compatibility.md#flow-preview-api) on source, binary and semantic compatibility.
 
 ### Changelog
 
-* A new [guide section](/docs/flow.md) about Flow.
+* A new [guide section](/docs/topics/flow.md) about Flow.
 * `CoroutineDispatcher.asExecutor` extension (#1450).
 * Fixed bug when `select` statement could report the same exception twice (#1433).
 * Fixed context preservation in `flatMapMerge` in a case when collected values were immediately emitted to another flow (#1440).
@@ -383,11 +383,11 @@ A lot of `Flow` improvements:
   * `flatMap`, `merge` and `concatenate` are replaced with `flattenConcat`, `flattenMerge`, `flatMapConcat` and `flatMapMerge`.
   * Various documentation improvements and minor bug fixes.
 
-Note that `Flow` **is not** leaving its [preview status](/docs/compatibility.md#flow-preview-api).
+Note that `Flow` **is not** leaving its [preview status](/docs/topics/compatibility.md#flow-preview-api).
 
 ## Version 1.2.0-alpha-2
 
-This release contains major [feature preview](/docs/compatibility.md#flow-preview-api): cold streams aka `Flow` (#254). 
+This release contains major [feature preview](/docs/topics/compatibility.md#flow-preview-api): cold streams aka `Flow` (#254). 
 
 Performance:
 * Performance of `Dispatcher.Main` initialization is significantly improved (#878).
@@ -510,7 +510,7 @@ Maintenance release:
   * `Job()` wih parent now also cancels parent on failure consistently with other scopes.
   * All coroutine builders and `Job` implementations propagate failure to the parent unless it is a `CancellationException`. 
   * Note, "scoping" builders don't "cancel the parent" verbatim, but rethrow the corresponding exception to the caller for handling.
-  * `SupervisorJob()` and `supervisorScope { ... }` are introduced, allowing for a flexible implementation of custom exception-handling policies, see a [new section in the guide on supervision](docs/exception-handling.md#supervision).
+  * `SupervisorJob()` and `supervisorScope { ... }` are introduced, allowing for a flexible implementation of custom exception-handling policies, see a [new section in the guide on supervision](docs/topics/exception-handling.md#supervision).
   * Got rid of `awaitAll` in documentation and rewrote `currentScope` section (see #624).
 * **[Major]** Coroutine scheduler is used for `Dispatchers.Default` by default instead of deprecated `CommonPool`.
   * "`DefaultDispatcher`" is used as a public name of the default impl (you'll see it thread names and in the guide).
@@ -569,7 +569,7 @@ Visible consequences of include more robust exception handling for large corouti
   * `currentScope` and `coroutineScope` builders are introduced to extract and provide `CoroutineScope`.
   * Factory methods to create `CoroutineScope` from `CoroutineContext` are introduced.
   * `CoroutineScope.isActive` became an extension property.
-  * New sections about structured concurrency in core guide: ["Structured concurrency"](docs/coroutines-guide.md#structured-concurrency), ["Scope builder"](docs/coroutines-guide.md#scope-builder) and ["Structured concurrency with async"](docs/coroutines-guide.md#structured-concurrency-with-async).
+  * New sections about structured concurrency in core guide: ["Structured concurrency"](docs/topics/coroutines-guide.md#structured-concurrency), ["Scope builder"](docs/topics/coroutines-guide.md#scope-builder) and ["Structured concurrency with async"](docs/topics/coroutines-guide.md#structured-concurrency-with-async).
   * New section in UI guide with Android example: ["Structured concurrency, lifecycle and coroutine parent-child hierarchy"](ui/coroutines-guide-ui.md#structured-concurrency,-lifecycle-and-coroutine-parent-child-hierarchy).
   * Deprecated reactive API is removed.
 * Dispatchers are renamed and grouped in the Dispatchers object (see #41 and #533):
@@ -589,7 +589,7 @@ Visible consequences of include more robust exception handling for large corouti
 ## Version 0.25.0
 
 * Major rework on exception-handling and cancellation in coroutines (see #333, #452 and #451):
-  * New ["Exception Handling" section in the guide](docs/coroutines-guide.md#exception-handling) explains exceptions in coroutines. 
+  * New ["Exception Handling" section in the guide](docs/topics/coroutines-guide.md#exception-handling) explains exceptions in coroutines. 
   * Semantics of `Job.cancel` resulting `Boolean` value changed — `true` means exception was handled by the job, caller shall handle otherwise.
   * Exceptions are properly propagated from children to parents.
   * Installed `CoroutineExceptionHandler` for a family of coroutines receives one aggregated exception in case of failure.
@@ -598,7 +598,7 @@ Visible consequences of include more robust exception handling for large corouti
 * Introduced support for thread-local elements in coroutines context (see #119):
   * `ThreadContextElement` API for custom thread-context sensitive context elements.
   * `ThreadLocal.asContextElement()` extension function to convert an arbitrary thread-local into coroutine context element.
-  * New ["Thread-local data" subsection in the guide](docs/coroutines-guide.md#thread-local-data) with examples.
+  * New ["Thread-local data" subsection in the guide](docs/topics/coroutines-guide.md#thread-local-data) with examples.
   * SLF4J Mapped Diagnostic Context (MDC) integration is provided via `MDCContext` element defined in [`kotlinx-coroutines-slf4j`](integration/kotlinx-coroutines-slf4j/README.md) integration module.
 * Introduced IO dispatcher to offload blocking I/O-intensive tasks (see #79).
 * Introduced `ExecutorCoroutineDispatcher` instead of `CloseableCoroutineDispatcher` (see #385). 
@@ -831,7 +831,7 @@ Visible consequences of include more robust exception handling for large corouti
 * Fixed `actor` and `produce` so that a cancellation of a Job cancels the underlying channel (closes and removes all the pending messages).  
 * Fixed sporadic failure of `example-context-06` (see #160)
 * Fixed hang of `Job.start` on lazy coroutine with attached `invokeOnCompletion` handler.
-* A more gradual introduction to `runBlocking` and coroutines in the [guide](docs/coroutines-guide.md) (see #166).
+* A more gradual introduction to `runBlocking` and coroutines in the [guide](docs/topics/coroutines-guide.md) (see #166).
 
 ## Version 0.19.3
 
@@ -882,7 +882,7 @@ Visible consequences of include more robust exception handling for large corouti
   * When a context is explicitly specified, `newCoroutineContext` function checks if there is any
     interceptor/dispatcher defined in the context and uses `DefaultDispatcher` if there is none.  
   * `DefaultDispatcher` is currently defined to be equal to `CommonPool`.     
-  * Examples in the [guide](docs/coroutines-guide.md) now start with `launch { ... }` code and explanation on the nature
+  * Examples in the [guide](docs/topics/coroutines-guide.md) now start with `launch { ... }` code and explanation on the nature
     and the need for coroutine context starts in "Coroutine context and dispatchers" section.  
 * Parent coroutines now wait for their children (see #125):
   * Job _completing_ state is introduced in documentation as a state in which parent coroutine waits for its children.
@@ -942,7 +942,7 @@ Visible consequences of include more robust exception handling for large corouti
 ## Version 0.17
 
 * `CompletableDeferred` is introduced as a set-once event-like communication primitive (see #70).
-  * [Coroutines guide](docs/coroutines-guide.md) uses it in a section on actors.
+  * [Coroutines guide](docs/topics/coroutines-guide.md) uses it in a section on actors.
   * `CompletableDeferred` is an interface with private impl (courtesy of @fvasco, see #86).
   * It extends `Deferred` interface with `complete` and `completeExceptionally` functions.
 * `Job.join` and `Deferred.await` wait until a cancelled coroutine stops execution (see #64). 
@@ -1088,15 +1088,15 @@ Visible consequences of include more robust exception handling for large corouti
 * `actor` coroutine builder.
 * Couple more examples for "Shared mutable state and concurrency" section and 
   "Channels are fair" section with ping-pong table example 
-  in [coroutines guide](docs/coroutines-guide.md).
+  in [coroutines guide](docs/topics/coroutines-guide.md).
 
 ## Version 0.11-rc
 
 * `select` expression with onJoin/onAwait/onSend/onReceive clauses.
 * `Mutex` is moved to `kotlinx.coroutines.sync` package.
 * `ClosedSendChannelException` is a subclass of `CancellationException` now.
 * New sections on "Shared mutable state and concurrency" and "Select expression" 
-  in [coroutines guide](docs/coroutines-guide.md).
+  in [coroutines guide](docs/topics/coroutines-guide.md).
 
 ## Version 0.10-rc
 
@@ -1124,20 +1124,20 @@ Visible consequences of include more robust exception handling for large corouti
   So, lazy coroutines do not need a separate state variable to track their started/not-started (new/active) status.
 * Exception transparency in `Job.cancel` (original cause is rethrown).
 * Clarified possible states for `Job`/`CancellableContinuation`/`Deferred` in docs.
-* Example on async-style functions and links to API reference site from [coroutines guide](docs/coroutines-guide.md).
+* Example on async-style functions and links to API reference site from [coroutines guide](docs/topics/coroutines-guide.md).
 
 ## Version 0.7-beta
 
 * Buffered and unbuffered channels are introduced: `Channel`, `SendChannel`, and `ReceiveChannel` interfaces,
   `RendezvousChannel` and `ArrayChannel` implementations, `Channel()` factory function and `buildChannel{}`
   coroutines builder.
 * `Here` context is renamed to `Unconfined` (the old name is deprecated).
-* A [guide on coroutines](docs/coroutines-guide.md) is expanded: sections on contexts and channels.  
+* A [guide on coroutines](docs/topics/coroutines-guide.md) is expanded: sections on contexts and channels.  
 
 ## Version 0.6-beta
 
 * Switched to Kotlin version 1.1.0-beta-37.
-* A [guide on coroutines](docs/coroutines-guide.md) is expanded.  
+* A [guide on coroutines](docs/topics/coroutines-guide.md) is expanded.  
 
 ## Version 0.5-beta
 
@@ -1150,7 +1150,7 @@ Visible consequences of include more robust exception handling for large corouti
   has a default implementation that returns `true`.
 * `NonCancellable` context is introduced.  
 * Performance optimizations for cancellable continuations (fewer objects created).
-* A [guide on coroutines](docs/coroutines-guide.md) is added.  
+* A [guide on coroutines](docs/topics/coroutines-guide.md) is added.  
 
 ## Version 0.4-beta
 

README.md

@@ -65,10 +65,10 @@ suspend fun main() = coroutineScope {
   * [Deep dive into Coroutines](https://www.youtube.com/watch?v=YrrUCSi72E8) (Roman Elizarov at KotlinConf 2017, [slides](https://www.slideshare.net/elizarov/deep-dive-into-coroutines-on-jvm-kotlinconf-2017))
   * [Kotlin Coroutines in Practice](https://www.youtube.com/watch?v=a3agLJQ6vt8) (Roman Elizarov at KotlinConf 2018, [slides](https://www.slideshare.net/elizarov/kotlin-coroutines-in-practice-kotlinconf-2018))
 * Guides and manuals: 
-  * [Guide to kotlinx.coroutines by example](https://kotlinlang.org/docs/reference/coroutines/coroutines-guide.html) (**read it first**)
+  * [Guide to kotlinx.coroutines by example](https://kotlinlang.org/docs/coroutines-guide.html) (**read it first**)
   * [Guide to UI programming with coroutines](ui/coroutines-guide-ui.md)
-  * [Debugging capabilities in kotlinx.coroutines](docs/debugging.md)
-* [Compatibility policy and experimental annotations](docs/compatibility.md)
+  * [Debugging capabilities in kotlinx.coroutines](docs/topics/debugging.md)
+* [Compatibility policy and experimental annotations](docs/topics/compatibility.md)
 * [Change log for kotlinx.coroutines](CHANGES.md)
 * [Coroutines design document (KEEP)](https://github.com/Kotlin/KEEP/blob/master/proposals/coroutines.md)
 * [Full kotlinx.coroutines API reference](https://kotlin.github.io/kotlinx.coroutines)
@@ -190,15 +190,15 @@ packagingOptions {
 
 ### JS
 
-[Kotlin/JS](https://kotlinlang.org/docs/reference/js-overview.html) version of `kotlinx.coroutines` is published as 
+[Kotlin/JS](https://kotlinlang.org/docs/js-overview.html) version of `kotlinx.coroutines` is published as 
 [`kotlinx-coroutines-core-js`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-js/1.4.2/jar)
 (follow the link to get the dependency declaration snippet).
 
 You can also use [`kotlinx-coroutines-core`](https://www.npmjs.com/package/kotlinx-coroutines-core) package via NPM. 
 
 ### Native
 
-[Kotlin/Native](https://kotlinlang.org/docs/reference/native-overview.html) version of `kotlinx.coroutines` is published as 
+[Kotlin/Native](https://kotlinlang.org/docs/native-overview.html) version of `kotlinx.coroutines` is published as 
 [`kotlinx-coroutines-core-native`](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-native/1.4.2/jar)
 (follow the link to get the dependency declaration snippet).