Revise documentation (#2728)

Co-authored-by: Sarah Haggarty <sarahhaggarty@users.noreply.github.com>

.github/workflows/gh-pages.yml

@@ -19,8 +19,8 @@ jobs:
         id: filter
         with:
           filters: |
-            docs_changed:
-              - 'docs/**'
+            mkdocs_changed:
+              - 'mkdocs/**'
           working-directory: ./dokka
       - uses: actions/setup-java@v3
         with:
@@ -30,17 +30,17 @@ jobs:
       - uses: gradle/gradle-build-action@v2
       - name: Get current dokka version
         run: echo "DOKKA_VERSION=`./gradlew :properties | grep '^version:.*' | cut -d ' ' -f 2`" >> $GITHUB_ENV
-        if: github.event_name == 'release' || steps.filter.outputs.docs_changed == 'true'
+        if: github.event_name == 'release' || steps.filter.outputs.mkdocs_changed == 'true'
         working-directory: ./dokka
       - name: Build docs
         run: ./gradlew mkdocsBuild -Pdokka_version=$DOKKA_VERSION --info
-        if: github.event_name == 'release' || steps.filter.outputs.docs_changed == 'true'
+        if: github.event_name == 'release' || steps.filter.outputs.mkdocs_changed == 'true'
         working-directory: ./dokka
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3
-        if: github.event_name == 'release' || steps.filter.outputs.docs_changed == 'true'
+        if: github.event_name == 'release' || steps.filter.outputs.mkdocs_changed == 'true'
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./dokka/docs/build/mkdocs
+          publish_dir: ./dokka/mkdocs/build/mkdocs
           keep_files: true
           full_commit_message: Publish ${{ env.DOKKA_VERSION }} documentation

CONTRIBUTING.md

@@ -29,7 +29,7 @@ Here's how to import and configure Dokka in IntelliJ IDEA:
 
 If you want to use/test your locally built Dokka in a project, do the following:
 1. Change `dokka_version` in `gradle.properties` to something that you will use later on as the dependency version.
-   For instance, you can set it to something like `1.7.20-my-fix-SNAPSHOT`.
+   For example, you can set it to something like `1.7.20-my-fix-SNAPSHOT`.
 2. Publish it to maven local (`./gradlew publishToMavenLocal`)
 3. In the project you want to generate documentation for, add maven local as a plugin/dependency
    repository (`mavenLocal()`)

core/api/core.api

@@ -57,10 +57,6 @@ public final class org/jetbrains/dokka/DokkaBootstrapImpl$DokkaProxyLogger : org
 	public fun warn (Ljava/lang/String;)V
 }
 
-public final class org/jetbrains/dokka/DokkaBootstrapImplKt {
-	public static final fun parsePerPackageOptions (Ljava/util/List;)Ljava/util/List;
-}
-
 public abstract interface class org/jetbrains/dokka/DokkaConfiguration : java/io/Serializable {
 	public abstract fun getCacheRoot ()Ljava/io/File;
 	public abstract fun getDelayTemplateSubstitution ()Z
@@ -212,9 +208,9 @@ public final class org/jetbrains/dokka/DokkaDefaults {
 	public static final field INSTANCE Lorg/jetbrains/dokka/DokkaDefaults;
 	public static final field delayTemplateSubstitution Z
 	public static final field failOnWarning Z
-	public static final field format Ljava/lang/String;
 	public static final field includeNonPublic Z
 	public static final field jdkVersion I
+	public static final field noAndroidSdkLink Z
 	public static final field noJdkLink Z
 	public static final field noStdlibLink Z
 	public static final field offlineMode Z
@@ -224,6 +220,7 @@ public final class org/jetbrains/dokka/DokkaDefaults {
 	public static final field sourceSetDisplayName Ljava/lang/String;
 	public static final field sourceSetName Ljava/lang/String;
 	public static final field suppress Z
+	public static final field suppressGeneratedFiles Z
 	public static final field suppressInheritedMembers Z
 	public static final field suppressObviousFunctions Z
 	public final fun getAnalysisPlatform ()Lorg/jetbrains/dokka/Platform;

core/src/main/kotlin/DokkaBootstrapImpl.kt

@@ -1,45 +1,9 @@
 package org.jetbrains.dokka
 
-import org.jetbrains.dokka.DokkaConfiguration.PackageOptions
 import org.jetbrains.dokka.utilities.DokkaLogger
 
 import java.util.function.BiConsumer
 
-
-fun parsePerPackageOptions(args: List<String>): List<PackageOptions> = args.map { it.split(",") }.map {
-    val matchingRegex = it.first()
-
-    val options = it.subList(1, it.size)
-
-    val deprecated = options.find { it.endsWith("skipDeprecated") }?.startsWith("+")
-        ?: DokkaDefaults.skipDeprecated
-
-    val reportUndocumented = options.find { it.endsWith("reportUndocumented") }?.startsWith("+")
-        ?: DokkaDefaults.reportUndocumented
-
-    val privateApi = options.find { it.endsWith("includeNonPublic") }?.startsWith("+")
-        ?: DokkaDefaults.includeNonPublic
-
-    val suppress = options.find { it.endsWith("suppress") }?.startsWith("+")
-        ?: DokkaDefaults.suppress
-
-    val documentedVisibilities = options
-        .filter { it.matches(Regex("\\+visibility:.+")) } // matches '+visibility:' with at least one symbol after the semicolon
-        .map { DokkaConfiguration.Visibility.fromString(it.split(":")[1]) }
-        .toSet()
-        .ifEmpty { DokkaDefaults.documentedVisibilities }
-
-    PackageOptionsImpl(
-        matchingRegex,
-        includeNonPublic = privateApi,
-        documentedVisibilities = documentedVisibilities,
-        reportUndocumented = reportUndocumented,
-        skipDeprecated = !deprecated,
-        suppress = suppress
-    )
-}
-
-
 /**
  * Accessed with reflection
  */

core/src/main/kotlin/configuration.kt

@@ -12,30 +12,38 @@ import java.net.URL
 
 object DokkaDefaults {
     val moduleName: String = "root"
+    val moduleVersion: String? = null
     val outputDir = File("./dokka")
-    const val format: String = "html"
-    val cacheRoot: File? = null
-    const val offlineMode: Boolean = false
     const val failOnWarning: Boolean = false
-    const val delayTemplateSubstitution: Boolean = false
+    const val suppressObviousFunctions = true
+    const val suppressInheritedMembers = false
+    const val offlineMode: Boolean = false
+
+    const val sourceSetDisplayName = "JVM"
+    const val sourceSetName = "main"
+    val analysisPlatform: Platform = Platform.DEFAULT
+
+    const val suppress: Boolean = false
+    const val suppressGeneratedFiles: Boolean = true
 
-    const val includeNonPublic: Boolean = false
-    val documentedVisibilities: Set<DokkaConfiguration.Visibility> = setOf(DokkaConfiguration.Visibility.PUBLIC)
-    const val reportUndocumented: Boolean = false
     const val skipEmptyPackages: Boolean = true
     const val skipDeprecated: Boolean = false
-    const val jdkVersion: Int = 8
+
+    const val reportUndocumented: Boolean = false
+
     const val noStdlibLink: Boolean = false
+    const val noAndroidSdkLink: Boolean = false
     const val noJdkLink: Boolean = false
-    val analysisPlatform: Platform = Platform.DEFAULT
-    const val suppress: Boolean = false
+    const val jdkVersion: Int = 8
+
+    const val includeNonPublic: Boolean = false
+    val documentedVisibilities: Set<DokkaConfiguration.Visibility> = setOf(DokkaConfiguration.Visibility.PUBLIC)
 
-    const val sourceSetDisplayName = "JVM"
-    const val sourceSetName = "main"
-    val moduleVersion: String? = null
     val pluginsConfiguration = mutableListOf<PluginConfigurationImpl>()
-    const val suppressObviousFunctions = true
-    const val suppressInheritedMembers = false
+
+    const val delayTemplateSubstitution: Boolean = false
+
+    val cacheRoot: File? = null
 }
 
 enum class Platform(val key: String) {
@@ -88,10 +96,12 @@ data class DokkaSourceSetID(
 fun DokkaConfigurationImpl(json: String): DokkaConfigurationImpl = parseJson(json)
 
 /**
- * Global options are applied to all packages and modules and overwrite package configuration.
+ * Global options can be configured and applied to all packages and modules at once, overwriting package configuration.
+ *
+ * These are handy if we have multiple source sets sharing the same global options as it reduces the size of the
+ * boilerplate. Otherwise, the user would be forced to repeat all these options for each source set.
  *
- * These are handy if we have multiple sourcesets sharing the same global options as it reduces the size of the boilerplate.
- * Otherwise, the user would be enforced to repeat all these options per each sourceset.
+ * @see [apply] to learn how to apply global configuration
  */
 data class GlobalDokkaConfiguration(
     val perPackageOptions: List<PackageOptionsImpl>?,

core/src/main/kotlin/defaultConfiguration.kt

@@ -71,9 +71,9 @@ data class SourceLinkDefinitionImpl(
         fun parseSourceLinkDefinition(srcLink: String): SourceLinkDefinitionImpl {
             val (path, urlAndLine) = srcLink.split('=')
             return SourceLinkDefinitionImpl(
-                File(path).canonicalPath,
-                URL(urlAndLine.substringBefore("#")),
-                urlAndLine.substringAfter("#", "").let { if (it.isEmpty()) null else "#$it" })
+                localDirectory = File(path).canonicalPath,
+                remoteUrl = URL(urlAndLine.substringBefore("#")),
+                remoteLineSuffix = urlAndLine.substringAfter("#", "").let { if (it.isEmpty()) null else "#$it" })
         }
     }
 }
@@ -85,7 +85,7 @@ data class PackageOptionsImpl(
     override val reportUndocumented: Boolean?,
     override val skipDeprecated: Boolean,
     override val suppress: Boolean,
-    override val documentedVisibilities: Set<DokkaConfiguration.Visibility>,
+    override val documentedVisibilities: Set<DokkaConfiguration.Visibility>, // TODO add default to DokkaDefaults.documentedVisibilities
 ) : DokkaConfiguration.PackageOptions
 
 

docs/README.md

@@ -0,0 +1,9 @@
+# Dokka documentation
+
+This folder contains the Dokka documentation that is available on [kotlinlang.org](https://kotlinlang.org/).
+
+Our documentation is written in Markdown format with some domain specific language (DSL) constructs that are used at 
+JetBrains.
+
+If you wish to contribute to the documentation, please read through 
+[Kotlin documentation guidelines](https://docs.google.com/document/d/1mUuxK4xwzs3jtDGoJ5_zwYLaSEl13g_SuhODdFuh2Dc/edit).

docs/cfg/buildprofiles.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<buildprofiles>
+    <variables>
+        <enable-browser-edits>true</enable-browser-edits>
+        <browser-edits-url>https://github.com/Kotlin/dokka/edit/master/docs/</browser-edits-url>
+        <allow-indexable-eaps>true</allow-indexable-eaps>
+    </variables>
+    <build-profile product="kl"/>
+</buildprofiles>

docs/dokka.tree

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE product-profile
+        SYSTEM "https://resources.jetbrains.com/stardust/product-profile.dtd">
+
+<product-profile id="kl"
+                 name="dokka"
+                 start-page="dokka-introduction.md">
+
+    <chunk include-id="dokka">
+        <toc-element id="dokka-introduction.md"/>
+        <toc-element id="dokka-get-started.md"/>
+        <toc-element toc-title="Run Dokka">
+            <toc-element id="dokka-gradle.md"/>
+            <toc-element id="dokka-maven.md"/>
+            <toc-element id="dokka-cli.md"/>
+        </toc-element>
+        <toc-element toc-title="Output formats">
+            <toc-element id="dokka-html.md"/>
+            <toc-element id="dokka-markdown.md"/>
+            <toc-element id="dokka-javadoc.md"/>
+        </toc-element>
+        <toc-element id="dokka-plugins.md"/>
+    </chunk>
+</product-profile>

docs/project.ihp

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE ihp SYSTEM "https://resources.jetbrains.com/stardust/ihp.dtd">
+
+<ihp version="2.0">
+<!--    <categories src="categories.list"/>-->
+    <module name="dokka"/>
+    <topics dir="topics"/>
+    <images dir="images"/>
+    <vars src="vars.list"/>
+    <product src="dokka.tree" version="%dokkaVersion%" />
+    <settings>
+        <default-property element-name="toc-element" property-name="show-structure-depth" value="2"/>
+    </settings>
+</ihp>

docs/topics/dokka-get-started.md

@@ -0,0 +1,95 @@
+[//]: # (title: Get started)
+
+Below you can find simple instructions to help you get started with Dokka.
+
+<tabs group="build-script">
+<tab title="Gradle Kotlin DSL" group-key="kotlin">
+
+Apply the Gradle plugin for Dokka in the root build script of your project:
+
+```kotlin
+plugins {
+    id("org.jetbrains.dokka") version "%dokkaVersion%"
+}
+```
+
+When documenting [multi-project](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need 
+to apply the Gradle plugin within subprojects as well:
+
+```kotlin
+subprojects {
+    apply(plugin = "org.jetbrains.dokka")
+}
+```
+
+To generate documentation, run the following Gradle tasks:
+
+* `dokkaHtml` for single-project builds
+* `dokkaHtmlMultiModule` for multi-project builds
+
+By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`.
+
+To learn more about using Dokka with Gradle, see [Gradle](dokka-gradle.md).
+
+</tab>
+<tab title="Gradle Groovy DSL" group-key="groovy">
+
+Apply the Gradle plugin for Dokka in the root build script of your project:
+
+```groovy
+plugins {
+    id 'org.jetbrains.dokka' version '%dokkaVersion%'
+}
+```
+
+When documenting [multi-project](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need
+to apply the Gradle plugin within subprojects as well:
+
+```groovy
+subprojects {
+    apply plugin: 'org.jetbrains.dokka'
+}
+```
+
+To generate documentation, run the following Gradle tasks:
+
+* `dokkaHtml` for single-project builds
+* `dokkaHtmlMultiModule` for multi-project builds
+
+By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`.
+
+To learn more about using Dokka with Gradle, see [Gradle](dokka-gradle.md).
+
+</tab>
+<tab title="Maven" group-key="mvn">
+
+Add the Maven plugin for Dokka to the `plugins` section of your POM file:
+
+```xml
+<build>
+    <plugins>
+        <plugin>
+            <groupId>org.jetbrains.dokka</groupId>
+            <artifactId>dokka-maven-plugin</artifactId>
+            <version>%dokkaVersion%</version>
+            <executions>
+                <execution>
+                    <phase>pre-site</phase>
+                    <goals>
+                        <goal>dokka</goal>
+                    </goals>
+                </execution>
+            </executions>
+        </plugin>
+    </plugins>
+</build>
+```
+
+To generate documentation, run the `dokka:dokka` goal.
+
+By default, the output directory is set to `target/dokka`.
+
+To learn more about using Dokka with Maven, see [Maven](dokka-maven.md).
+
+</tab>
+</tabs>

docs/topics/dokka-introduction.md

@@ -0,0 +1,28 @@
+[//]: # (title: Introduction)
+
+Dokka is an API documentation engine for Kotlin.
+
+Just like Kotlin itself, Dokka supports mixed-language projects. It understands Kotlin's
+[KDoc comments](https://kotlinlang.org/docs/kotlin-doc.html#kdoc-syntax) and Java's 
+[Javadoc comments](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html).
+
+Dokka can generate documentation in multiple formats, including its own modern [HTML format](dokka-html.md),
+multiple flavors of [Markdown](dokka-markdown.md), and Java's [Javadoc HTML](dokka-javadoc.md).
+
+Here are some libraries that use Dokka for their API reference documentation:
+
+* [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/)
+* [Bitmovin](https://cdn.bitmovin.com/player/android/3/docs/index.html)
+* [Hexagon](https://hexagonkt.com/api/index.html)
+* [Ktor](https://api.ktor.io/)
+* [OkHttp](https://square.github.io/okhttp/4.x/okhttp/okhttp3/) (Markdown)
+
+You can run Dokka using [Gradle](dokka-gradle.md), [Maven](dokka-maven.md) or from the [command line](dokka-cli.md). It is also
+[highly pluggable](dokka-plugins.md).
+
+See [Get started](dokka-get-started.md) to take your first steps in using Dokka.
+
+## Community
+
+Dokka has a dedicated `#dokka` channel in [Kotlin Community Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up)
+where you can chat about Dokka, its plugins and how to develop them, as well as get in touch with maintainers.