diff options
78 files changed, 5734 insertions, 626 deletions
diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 9a744d38..8bb860fe 100644 --- a/.github/workflows/gh-pages.yml +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 92bc9105..ca58ff4d 100644 --- a/CONTRIBUTING.md +++ b/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()`) diff --git a/core/api/core.api b/core/api/core.api index 7d29d872..c85a3347 100644 --- a/core/api/core.api +++ b/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; diff --git a/core/src/main/kotlin/DokkaBootstrapImpl.kt b/core/src/main/kotlin/DokkaBootstrapImpl.kt index 75c4c0af..114bade7 100644 --- a/core/src/main/kotlin/DokkaBootstrapImpl.kt +++ b/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 */ diff --git a/core/src/main/kotlin/configuration.kt b/core/src/main/kotlin/configuration.kt index c26faf28..77384ace 100644 --- a/core/src/main/kotlin/configuration.kt +++ b/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>?, diff --git a/core/src/main/kotlin/defaultConfiguration.kt b/core/src/main/kotlin/defaultConfiguration.kt index 8c7c8b5d..66154570 100644 --- a/core/src/main/kotlin/defaultConfiguration.kt +++ b/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 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..686c95bd --- /dev/null +++ b/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). diff --git a/docs/cfg/buildprofiles.xml b/docs/cfg/buildprofiles.xml new file mode 100644 index 00000000..86c3ad59 --- /dev/null +++ b/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> diff --git a/docs/dokka.tree b/docs/dokka.tree new file mode 100644 index 00000000..73ac277e --- /dev/null +++ b/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> diff --git a/docs/images/dokkaHtmlCollector-example.png b/docs/images/dokkaHtmlCollector-example.png Binary files differnew file mode 100644 index 00000000..5bd74d8d --- /dev/null +++ b/docs/images/dokkaHtmlCollector-example.png diff --git a/docs/images/dokkaHtmlMultiModule-example.png b/docs/images/dokkaH |
