Add Mkdocs plugin to Gradle, split README and Developers' guide into several files

1 files changed, 4 insertions, 426 deletions

diff --git a/README.md b/README.md
index ed2d38c2..a82ac73b 100644
--- a/README.md
+++ b/README.md
@@ -7,48 +7,7 @@ and can generate documentation in multiple formats including standard Javadoc, H
 
 ## Using dokka
 
-### Plugins 
-Dokka can be customized with plugins. Each output format is internally a plugin.
-Additionally, `kotlin-as-java` plugin can be used to generate documentation as seen from Java perspective. 
-Currently maintained plugins are:
-* `dokka-base` - the main plugin needed to run dokka, contains html format
-* `gfm-plugin` - configures `GFM` output format
-* `jekyll-plugin` - configures `Jekyll` output format
-* `javadoc-plugin` - configures `Javadoc` output format, automatically applies `kotlin-as-java-plugin` 
-* `kotlin-as-java-plugin` - translates Kotlin definitions to Java 
-
-Please see the usage instructions below for how to add plugins to dokka. 
-
-### Source sets 
-Dokka generates documentation based on source sets. 
-
-For single-platform & multi-platform projects, source sets are the same as in Kotlin plugin:
-
- * One source set for each platform, eg. `jvmMain` or `jsMain`;
- * One source set for each common source set, eg. the default `commonMain` and custom ones like `jsAndJvmMain`.
-
-When configuring multi-platform projects manually (eg. in the CLI or in Gradle without the Kotlin Gradle Plugin)
-source sets must declare their dependent source sets. 
-Eg. in the following Kotlin plugin configuration:
-
-* `jsMain` and `jvmMain` both depend on `commonMain` (by default and transitively) and `jsAndJvmMain`;
-* `linuxX64Main` only depends on `commonMain`. 
-
-```kotlin
-kotlin { // Kotlin plugin configuration
-    jvm()
-    js()
-    linuxX64()
-
-    sourceSets {
-        val commonMain by getting {}
-        val jvmAndJsSecondCommonMain by creating { dependsOn(commonMain) }
-        val jvmMain by getting { dependsOn(jvmAndJsSecondCommonMain) }
-        val jsMain by getting { dependsOn(jvmAndJsSecondCommonMain) }
-        val linuxX64Main by getting { dependsOn(commonMain) }
-    }
-}
-```
+**Full documentation is available at [http://kotlin.github.io/dokka](http://kotlin.github.io/dokka)**
 
 ### Using the Gradle plugin
 _Note: If you are upgrading from 0.10.x to a current release of dokka, please have a look at our 
@@ -78,194 +37,8 @@ pluginManagement {
 }
 ```
 
-You can also use the legacy plugin application method with `buildscript` block.
-Note that by using the `buildscript` way type-safe accessors are not available in Gradle Kotlin DSL,
-eg. you'll have to use `named<DokkaTask>("dokkaHtml")` instead of `dokkaHtml`:
-
-```kotlin
-buildscript {
-    repositories {
-        jcenter()
-    }
-    dependencies {
-        classpath("org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}")
-    }
-}
-repositories {
-    jcenter() // or maven(url="https://dl.bintray.com/kotlin/dokka")
-}
-
-apply(plugin="org.jetbrains.dokka")
-```
-
 The plugin adds `dokkaHtml`, `dokkaJavadoc`, `dokkaGfm` and `dokkaJekyll` tasks to the project.
  
-Each task corresponds to one output format, so you should run `dokkaGfm` when you want to have a documentation in `GFM` format.
-Output formats are explained [there](#output_formats)
-
-If you encounter any problems when migrating from older versions of dokka, please see the [FAQ](https://github.com/Kotlin/dokka/wiki/faq).
-
-Minimal dokka configuration (with only custom output directory)
-
-Kotlin
-```kotlin
-tasks.dokkaHtml.configure {
-    outputDirectory.set(buildDir.resolve("dokka"))
-}
-```
-
-
-Groovy
-```kotlin
-tasks.named("dokkaHtml") {
-    outputDirectory.set(buildDir.resolve("dokka"))
-}
-```
-
-
-Dokka documents single-platform as well as multi-platform projects. 
-Most of the configuration options are set per one source set.
-The available configuration options for are shown below:
-
-```kotlin
-dokkaHtml {
-    outputDirectory.set(buildDir.resolve("dokka"))
-
-    // Used for disabling auto extraction of sources and platforms
-    // When set to true kotlinTasks are also omitted
-    disableAutoconfiguration.set(false)
-
-    // Use default or set to custom path to cache directory
-    // to enable package-list caching
-    // When this is set to default, caches are stored in $USER_HOME/.cache/dokka
-    cacheRoot.set(file("default"))
-    dokkaSourceSets {
-        configureEach { // Or source set name, for single-platform the default source sets are `main` and `test`
-
-            // Used when configuring source sets manually for declaring which source sets this one depends on
-            dependsOn("otherSourceSetName")
-
-            // Use to include or exclude non public members
-            includeNonPublic.set(false)
-
-            // Do not output deprecated members. Applies globally, can be overridden by packageOptions
-            skipDeprecated.set(false)
-
-            // Emit warnings about not documented members. Applies globally, also can be overridden by packageOptions
-            reportUndocumented.set(true)
-
-            // Do not create index pages for empty packages
-            skipEmptyPackages.set(true)
-
-            // This name will be shown in the final output
-            displayName.set("JVM")
-
-            // Platform used for code analysis. See the "Platforms" section of this readme
-            platform.set(org.jetbrains.dokka.Platform.jvm)
-
-            // Property used for manual addition of files to the classpath
-            // This property does not override the classpath collected automatically but appends to it
-            classpath.from(file("libs/dependency.jar"))
-
-            // List of files with module and package documentation
-            // https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation
-            includes.from("packages.md", "extra.md")
-
-            // List of files or directories containing sample code (referenced with @sample tags)
-            samples.from("samples/basic.kt", "samples/advanced.kt")
-
-            // By default, sourceRoots are taken from Kotlin Plugin and kotlinTasks, following roots will be appended to them
-            // Repeat for multiple sourceRoots
-            sourceRoot.from(file("src"))
-
-            // Specifies the location of the project source code on the Web.
-            // If provided, Dokka generates "source" links for each declaration.
-            // Repeat for multiple mappings
-            sourceLink {
-                // Unix based directory relative path to the root of the project (where you execute gradle respectively). 
-                localDirectory.set(file("src/main/kotlin"))
-
-                // URL showing where the source code can be accessed through the web browser
-                remoteUrl.set(java.net.URL(
-                    "https://github.com/cy6erGn0m/vertx3-lang-kotlin/blob/master/src/main/kotlin"))
-                // Suffix which is used to append the line number to the URL. Use #L for GitHub
-                remoteLineSuffix.set("#L")
-            }
-
-            // Used for linking to JDK documentation
-            jdkVersion.set(8)
-
-            // Disable linking to online kotlin-stdlib documentation
-            noStdlibLink.set(false)
-
-            // Disable linking to online JDK documentation
-            noJdkLink.set(false)
-
-            // Disable linking to online Android documentation (only applicable for Android projects)
-            noAndroidSdkLink.set(false)
-
-            // Allows linking to documentation of the project"s dependencies (generated with Javadoc or Dokka)
-            // Repeat for multiple links
-            externalDocumentationLink {
-                // Root URL of the generated documentation to link with. The trailing slash is required!
-                url = URL("https://example.com/docs/")
-
-                // If package-list file is located in non-standard location
-                // packageListUrl = URL("file:///home/user/localdocs/package-list")
-            }
-
-            // Allows to customize documentation generation options on a per-package basis
-            // Repeat for multiple packageOptions
-            perPackageOption {
-                prefix.set("kotlin") // will match kotlin and all sub-packages of it
-                // All options are optional, default values are below:
-                skipDeprecated.set(false)
-                reportUndocumented.set(true) // Emit warnings about not documented members 
-                includeNonPublic.set(false)
-            }
-            // Suppress a package
-            perPackageOption {
-                prefix.set("kotlin.internal") // will match kotlin.internal and all sub-packages of it
-                suppress.set(true)
-            }
-        }
-    }
-```
-
-#### Multiplatform
-Dokka supports single-platform and multi-platform projects using source sets abstraction. For most mutli-platform projects
-you should assume that dokka's source sets correspond to Kotlin plugin's source sets. Main source sets will be registered
-and configured automatically
-
-Kotlin
-```kotlin
-kotlin {  // Kotlin Multiplatform plugin configuration
-    jvm()
-    js("customName")
-}
-
-tasks.withType<DokkaTask>().configureEach {
-        // custom output directory
-        outputDirectory.set(buildDir.resolve("dokka"))
-
-        dokkaSourceSets { 
-             named("customNameMain") { // The same name as in Kotlin Multiplatform plugin, so the sources are fetched automatically
-                includes.from("packages.md", "extra.md")
-                samples.from("samples/basic.kt", "samples/advanced.kt")
-            }
-
-            register("differentName") { // Different name, so source roots must be passed explicitly
-                displayName = "JVM"
-                platform = "jvm"
-                sourceRoots.from(kotlin.sourceSets.getByName("jvmMain").kotlin.srcDirs)
-                sourceRoots.from(kotlin.sourceSets.getByName("commonMain").kotlin.srcDirs)
-            }
-        }
-    }
-```
-
-If you want to share the configuration between source sets, you can use Gradle's `configureEach`
-
 #### Applying plugins
 Dokka plugin creates Gradle configuration for each output format in the form of `dokka${format}Plugin`:
 
@@ -295,9 +68,6 @@ To generate the documentation, use the appropriate `dokka${format}` Gradle task:
 
 Please see the [Dokka Gradle example project](https://github.com/Kotlin/kotlin-examples/tree/master/gradle/dokka/dokka-gradle-example) for an example.
 
-#### FAQ
-If you encounter any problems, please see the [FAQ](https://github.com/Kotlin/dokka/wiki/faq).
-
 #### Android
 
 Make sure you apply dokka after `com.android.library` and `kotlin-android`.
@@ -359,25 +129,7 @@ The Maven plugin is available in JCenter. You need to add the JCenter repository
 </pluginRepositories>
 ```
 
-Minimal Maven configuration is
-
-```xml
-<plugin>
-    <groupId>org.jetbrains.dokka</groupId>
-    <artifactId>dokka-maven-plugin</artifactId>
-    <version>${dokka.version}</version>
-    <executions>
-        <execution>
-            <phase>pre-site</phase>
-            <goals>
-                <goal>dokka</goal>
-            </goals>
-        </execution>
-    </executions>
-</plugin>
-```
-
-By default files will be generated in `target/dokka`.
+Documentation is by default generated in `target/dokka`.
 
 The following goals are provided by the plugin:
 
@@ -385,127 +137,6 @@ The following goals are provided by the plugin:
   * `dokka:javadoc` - generate HTML documentation in Javadoc format (showing declarations in Java syntax)
   * `dokka:javadocJar` - generate a .jar file with Javadoc format documentation
 
-The available configuration options are shown below:
-
-```xml
-<plugin>
-    <groupId>org.jetbrains.dokka</groupId>
-    <artifactId>dokka-maven-plugin</artifactId>
-    <version>${dokka.version}</version>
-    <executions>
-        <execution>
-            <phase>pre-site</phase>
-            <goals>
-                <goal>dokka</goal>
-            </goals>
-        </execution>
-    </executions>
-    <configuration>
-    
-        <!-- Set to true to skip dokka task, default: false -->
-        <skip>false</skip>
-    
-        <!-- Default: ${project.artifactId} -->
-        <moduleName>data</moduleName>
-
-        <!-- Default: ${project.basedir}/target/dokka -->
-        <outputDir>some/out/dir</outputDir>
-        
-        <!-- Use default or set to custom path to cache directory to enable package-list caching. -->
-        <!-- When set to default, caches stored in $USER_HOME/.cache/dokka -->
-        <cacheRoot>default</cacheRoot>
-
-        <!-- List of '.md' files with package and module docs -->
-        <!-- https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation -->
-        <includes>
-            <include>packages.md</include>
-            <include>extra.md</include>
-        </includes>
-        
-        <!-- List of sample roots -->
-        <samples>
-            <dir>src/test/samples</dir>
-        </samples>
-        
-        <!-- Used for linking to JDK, default: 6 -->
-        <jdkVersion>6</jdkVersion>
-
-        <!-- Do not output deprecated members, applies globally, can be overridden by packageOptions -->
-        <skipDeprecated>false</skipDeprecated> 
-        <!-- Emit warnings about not documented members, applies globally, also can be overridden by packageOptions -->
-        <reportUndocumented>true</reportUndocumented>             
-        <!-- Do not create index pages for empty packages -->
-        <skipEmptyPackages>true</skipEmptyPackages> 
-        
-        <!-- Short form list of sourceRoots, by default, set to ${project.compileSourceRoots} -->
-        <sourceDirectories>
-            <dir>src/main/kotlin</dir>
-        </sourceDirectories>
-        
-        <!-- Full form list of sourceRoots -->
-        <sourceRoots>
-            <root>
-                <path>src/main/kotlin</path>
-                <!-- See platforms section of documentation -->
-                <platforms>JVM</platforms>
-            </root>
-        </sourceRoots>
-        
-        <!-- Specifies the location of the project source code on the Web. If provided, Dokka generates "source" links
-             for each declaration. -->
-        <sourceLinks>
-            <link>
-                <!-- Source directory -->
-                <path>${project.basedir}/src/main/kotlin</path>
-                <!-- URL showing where the source code can be accessed through the web browser -->
-                <url>https://github.com/cy6erGn0m/vertx3-lang-kotlin/blob/master/src/main/kotlin</url> <!-- //remove src/main/kotlin if you use "./" above -->
-                <!--Suffix which is used to append the line number to the URL. Use #L for GitHub -->
-                <lineSuffix>#L</lineSuffix>
-            </link>
-        </sourceLinks>
-        
-        <!-- Disable linking to online kotlin-stdlib documentation  -->
-        <noStdlibLink>false</noStdlibLink>
-        
-        <!-- Disable linking to online JDK documentation -->
-        <noJdkLink>false</noJdkLink>
-        
-        <!-- Allows linking to documentation of the project's dependencies (generated with Javadoc or Dokka) -->
-        <externalDocumentationLinks>
-            <link>
-                <!-- Root URL of the generated documentation to link with. The trailing slash is required! -->
-                <url>https://example.com/docs/</url>
-                <!-- If package-list file located in non-standard location -->
-                <!-- <packageListUrl>file:///home/user/localdocs/package-list</packageListUrl> -->
-            </link>
-        </externalDocumentationLinks>
-
-        <!-- Allows to customize documentation generation options on a per-package basis -->
-        <perPackageOptions>
-            <packageOptions>
-                <!-- Will match kotlin and all sub-packages of it -->
-                <prefix>kotlin</prefix>
-                
-                <!-- All options are optional, default values are below: -->
-                <skipDeprecated>false</skipDeprecated>
-                <!-- Emit warnings about not documented members  -->
-                <reportUndocumented>true</reportUndocumented>
-                <includeNonPublic>false</includeNonPublic>
-            </packageOptions>
-        </perPackageOptions>
-        
-        <!-- Allows to use any dokka plugin, eg. GFM format   -->
-        <dokkaPlugins>
-            <plugin>
-                <groupId>org.jetbrains.dokka</groupId>
-                <artifactId>gfm-plugin</artifactId>
-                <version>${dokka.version}</version>
-            </plugin>
-        </dokkaPlugins>
-    </configuration>
-</plugin>
-```
-
 #### Applying plugins
 You can add plugins inside the `dokkaPlugins` block:
 
@@ -543,36 +174,6 @@ To generate documentation, run the following command:
 ```
 java -jar dokka-cli.jar <arguments>
 ```
-Dokka supports the following command line arguments:
-
-  * `-outputDir` - the output directory where the documentation is generated
-  * `-cacheRoot` - cache directory to enable package-list caching
-  * `-pluginsClasspath` - artifacts with dokka plugins, separated by `;`. At least dokka base and all its dependencies must be added there 
-  * `-offlineMode` - do not resolve package-lists online
-  * `-failOnWarning` - throw an exception instead of a warning
-  * `-globalPackageOptions` - per package options added to all source sets
-  * `-globalLinks` - external documentation links added to all source sets
-  * `-globalSrcLink` - source links added to all source sets
-  * `-sourceSet` - (repeatable) - configuration for a single source set. Following this argument, you can pass other arguments:
-    * `-moduleName` - (required) - module name used as a part of source set ID when declaring dependent source sets
-    * `-sourceSetName` - source set name as a part of source set ID when declaring dependent source sets
-    * `-displayName` - source set name displayed in the generated documentation
-    * `-src` - list of source files or directories separated by `;`
-    * `-classpath` - list of directories or .jar files to include in the classpath (used for resolving references) separated by `;`
-    * `-samples` - list of directories containing sample code (documentation for those directories is not generated but declarations from them can be referenced using the `@sample` tag) separated by `;`
-    * `-includes` - list of files containing the documentation for the module and individual packages separated by `;`
-    * `-includeNonPublic` - include protected and private code   
-    * `-skipDeprecated` - if set, deprecated elements are not included in the generated documentation
-    * `-reportUndocumented` - warn about undocumented members
-    * `-skipEmptyPackages` - do not create index pages for empty packages
-    * `-packageOptions` - list of package options in format `prefix,-deprecated,-privateApi,+reportUndocumented;prefix, ...`, separated by `;`
-    * `-links` - list of external documentation links in format `url^packageListUrl^^url2...`, separated by `;`
-    * `-srcLink` - mapping between a source directory and a Web site for browsing the code in format `<path>=<url>[#lineSuffix]`
-    * `-noStdlibLink` - disable linking to online kotlin-stdlib documentation
-    * `-noJdkLink` - disable linking to online JDK documentation
-    * `-jdkVersion` - version of JDK to use for linking to JDK JavaDoc
-    * `-analysisPlatform` - platform used for analysis, see the [Platforms](#platforms) section
-    * `-dependentSourceSets` - list of dependent source sets in format `moduleName/sourceSetName`, separated by `;`
 
 You can also use a JSON file with dokka configuration:
  ```
@@ -597,28 +198,5 @@ dependencies{
 }
 ```
 
-### Platforms<a name="platforms"></a>
-
-Each dokka source set is analyzed for a specific platform. The platform should be extracted automatically from the Kotlin plugin.
-In case of a manual source set configuration, you have to select one of the following:
-  * `jvm`
-  * `js`
-  * `native`
-  * `common` 
-
-## Building dokka
-
-Dokka is built with Gradle. To build it, use `./gradlew build`.
-Alternatively, open the project directory in IntelliJ IDEA and use the IDE to build and run dokka.
-
-Here's how to import and configure Dokka in IntelliJ IDEA 2019.3:
- * Select "Open" from the IDEA welcome screen, or File > Open if a project is
-  already open
-* Select the directory with your clone of Dokka
-  * Note: IDEA may have an error after the project is initally opened; it is OK
-    to ignore this as the next step will address this error
-* After IDEA opens the project, select File > New > Module from existing sources
-  and select the `build.gradle` file from the root directory of your Dokka clone
-* After Dokka is loaded into IDEA, open the Gradle tool window (View > Tool
-  Windows > Gradle) and click on the top left "Refresh all Gradle projects"
-  button
+#### FAQ
+If you encounter any problems, please see the [FAQ](https://github.com/Kotlin/dokka/wiki/faq).