From 7544a215fb580ae0c47d1f397334f150d1a1ec65 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Tue, 10 Jan 2023 13:14:43 +0100 Subject: Revise documentation (#2728) Co-authored-by: Sarah Haggarty --- .github/workflows/gh-pages.yml | 12 +- CONTRIBUTING.md | 2 +- core/api/core.api | 7 +- core/src/main/kotlin/DokkaBootstrapImpl.kt | 36 - core/src/main/kotlin/configuration.kt | 46 +- core/src/main/kotlin/defaultConfiguration.kt | 8 +- docs/README.md | 9 + docs/build.gradle.kts | 3 - docs/cfg/buildprofiles.xml | 10 + docs/dokka.tree | 24 + docs/images/dokkaHtmlCollector-example.png | Bin 0 -> 94387 bytes docs/images/dokkaHtmlMultiModule-example.png | Bin 0 -> 52393 bytes docs/images/javadoc-format-example.png | Bin 0 -> 168563 bytes docs/images/versioning-plugin-example.png | Bin 0 -> 43684 bytes docs/project.ihp | 14 + docs/src/doc/docs/community/plugins-list.md | 160 -- docs/src/doc/docs/community/slack.md | 7 - .../architecture/architecture_overview.md | 123 -- .../architecture/data_model/documentables.md | 245 --- .../architecture/data_model/extra.md | 99 -- .../architecture/data_model/page_content.md | 140 -- .../extension_points/base_extensions.md | 13 - .../extension_points/core_extensions.md | 151 -- .../architecture/extension_points/introduction.md | 163 -- docs/src/doc/docs/developer_guide/introduction.md | 19 - .../plugin-development/introduction.md | 59 - .../plugin-development/sample-plugin-tutorial.md | 292 ---- docs/src/doc/docs/developer_guide/workflow.md | 100 -- docs/src/doc/docs/dokka_colors.css | 3 - docs/src/doc/docs/faq.md | 2 - docs/src/doc/docs/favicon.svg | 10 - docs/src/doc/docs/images/mathjax_demo.png | Bin 31853 -> 0 bytes docs/src/doc/docs/images/mermaid_demo.png | Bin 91709 -> 0 bytes docs/src/doc/docs/index.md | 38 - docs/src/doc/docs/survey_banner.js | 8 - docs/src/doc/docs/user_guide/applying/cli.md | 158 -- docs/src/doc/docs/user_guide/applying/gradle.md | 380 ----- docs/src/doc/docs/user_guide/applying/maven.md | 243 --- docs/src/doc/docs/user_guide/introduction.md | 74 - .../src/doc/docs/user_guide/output-formats/html.md | 112 -- .../doc/docs/user_guide/plugins/android-plugin.md | 8 - .../docs/user_guide/plugins/versioning-plugin.md | 86 -- docs/src/doc/mkdocs.yml | 99 -- docs/topics/dokka-get-started.md | 95 ++ docs/topics/dokka-introduction.md | 28 + docs/topics/dokka-plugins.md | 278 ++++ docs/topics/formats/dokka-html.md | 282 ++++ docs/topics/formats/dokka-javadoc.md | 93 ++ docs/topics/formats/dokka-markdown.md | 172 +++ docs/topics/runners/dokka-cli.md | 859 +++++++++++ docs/topics/runners/dokka-gradle.md | 1557 ++++++++++++++++++++ docs/topics/runners/dokka-maven.md | 646 ++++++++ docs/vars.list | 9 + examples/maven/pom.xml | 2 +- mkdocs/build.gradle.kts | 3 + mkdocs/src/doc/docs/community/plugins-list.md | 160 ++ mkdocs/src/doc/docs/community/slack.md | 7 + .../architecture/architecture_overview.md | 123 ++ .../architecture/data_model/documentables.md | 245 +++ .../architecture/data_model/extra.md | 99 ++ .../architecture/data_model/page_content.md | 140 ++ .../extension_points/base_extensions.md | 13 + .../extension_points/core_extensions.md | 151 ++ .../architecture/extension_points/introduction.md | 163 ++ .../src/doc/docs/developer_guide/introduction.md | 19 + .../plugin-development/introduction.md | 59 + .../plugin-development/sample-plugin-tutorial.md | 292 ++++ mkdocs/src/doc/docs/developer_guide/workflow.md | 100 ++ mkdocs/src/doc/docs/dokka_colors.css | 3 + mkdocs/src/doc/docs/faq.md | 2 + mkdocs/src/doc/docs/favicon.svg | 10 + mkdocs/src/doc/docs/images/mathjax_demo.png | Bin 0 -> 31853 bytes mkdocs/src/doc/docs/images/mermaid_demo.png | Bin 0 -> 91709 bytes mkdocs/src/doc/docs/index.md | 38 + mkdocs/src/doc/docs/survey_banner.js | 8 + mkdocs/src/doc/docs/user_guide/applying/cli.md | 158 ++ mkdocs/src/doc/docs/user_guide/applying/gradle.md | 380 +++++ mkdocs/src/doc/docs/user_guide/applying/maven.md | 243 +++ mkdocs/src/doc/docs/user_guide/introduction.md | 74 + .../src/doc/docs/user_guide/output-formats/html.md | 112 ++ .../doc/docs/user_guide/plugins/android-plugin.md | 8 + .../docs/user_guide/plugins/versioning-plugin.md | 86 ++ mkdocs/src/doc/mkdocs.yml | 99 ++ .../kotlin/org/jetbrains/dokka/gfm/GfmPlugin.kt | 5 +- .../org/jetbrains/dokka/javadoc/JavadocPlugin.kt | 6 +- plugins/jekyll/src/main/kotlin/JekyllPlugin.kt | 5 +- runners/cli/api/cli.api | 10 +- .../kotlin/org/jetbrains/dokka/CliArgumentTypes.kt | 91 ++ .../kotlin/org/jetbrains/dokka/GlobalArguments.kt | 164 +++ .../main/kotlin/org/jetbrains/dokka/LinkMapper.kt | 37 + .../org/jetbrains/dokka/PackageOptionsParser.kt | 34 + .../jetbrains/dokka/SourceSetArgumentsParser.kt | 155 ++ .../src/main/kotlin/org/jetbrains/dokka/main.kt | 429 +----- .../jetbrains/dokka/gradle/AbstractDokkaTask.kt | 134 +- .../jetbrains/dokka/gradle/DokkaMultiModuleTask.kt | 27 + .../jetbrains/dokka/gradle/DokkaSourceSetMapper.kt | 72 + .../dokka/gradle/GradleDokkaSourceSetBuilder.kt | 353 ++++- .../GradleDokkaSourceSetBuilderExtensions.kt | 9 + .../GradleExternalDocumentationLinkBuilder.kt | 48 + .../dokka/gradle/GradlePackageOptionsBuilder.kt | 74 +- .../dokka/gradle/GradleSourceLinkBuilder.kt | 50 + .../jetbrains/dokka/gradle/toDokkaSourceSetImpl.kt | 72 - runners/maven-plugin/api/maven-plugin.api | 32 +- runners/maven-plugin/src/main/kotlin/DokkaMojo.kt | 289 +++- .../kotlin/ExternalDocumentationLinkBuilder.kt | 63 + .../maven-plugin/src/main/kotlin/PackageOptions.kt | 85 ++ .../src/main/kotlin/SourceLinkMapItem.kt | 65 + settings.gradle.kts | 4 +- 108 files changed, 8600 insertions(+), 3492 deletions(-) create mode 100644 docs/README.md delete mode 100644 docs/build.gradle.kts create mode 100644 docs/cfg/buildprofiles.xml create mode 100644 docs/dokka.tree create mode 100644 docs/images/dokkaHtmlCollector-example.png create mode 100644 docs/images/dokkaHtmlMultiModule-example.png create mode 100644 docs/images/javadoc-format-example.png create mode 100644 docs/images/versioning-plugin-example.png create mode 100644 docs/project.ihp delete mode 100644 docs/src/doc/docs/community/plugins-list.md delete mode 100644 docs/src/doc/docs/community/slack.md delete mode 100644 docs/src/doc/docs/developer_guide/architecture/architecture_overview.md delete mode 100644 docs/src/doc/docs/developer_guide/architecture/data_model/documentables.md delete mode 100644 docs/src/doc/docs/developer_guide/architecture/data_model/extra.md delete mode 100644 docs/src/doc/docs/developer_guide/architecture/data_model/page_content.md delete mode 100644 docs/src/doc/docs/developer_guide/architecture/extension_points/base_extensions.md delete mode 100644 docs/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md delete mode 100644 docs/src/doc/docs/developer_guide/architecture/extension_points/introduction.md delete mode 100644 docs/src/doc/docs/developer_guide/introduction.md delete mode 100644 docs/src/doc/docs/developer_guide/plugin-development/introduction.md delete mode 100644 docs/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md delete mode 100644 docs/src/doc/docs/developer_guide/workflow.md delete mode 100644 docs/src/doc/docs/dokka_colors.css delete mode 100644 docs/src/doc/docs/faq.md delete mode 100755 docs/src/doc/docs/favicon.svg delete mode 100644 docs/src/doc/docs/images/mathjax_demo.png delete mode 100644 docs/src/doc/docs/images/mermaid_demo.png delete mode 100644 docs/src/doc/docs/index.md delete mode 100644 docs/src/doc/docs/survey_banner.js delete mode 100644 docs/src/doc/docs/user_guide/applying/cli.md delete mode 100644 docs/src/doc/docs/user_guide/applying/gradle.md delete mode 100644 docs/src/doc/docs/user_guide/applying/maven.md delete mode 100644 docs/src/doc/docs/user_guide/introduction.md delete mode 100644 docs/src/doc/docs/user_guide/output-formats/html.md delete mode 100644 docs/src/doc/docs/user_guide/plugins/android-plugin.md delete mode 100644 docs/src/doc/docs/user_guide/plugins/versioning-plugin.md delete mode 100644 docs/src/doc/mkdocs.yml create mode 100644 docs/topics/dokka-get-started.md create mode 100644 docs/topics/dokka-introduction.md create mode 100644 docs/topics/dokka-plugins.md create mode 100644 docs/topics/formats/dokka-html.md create mode 100644 docs/topics/formats/dokka-javadoc.md create mode 100644 docs/topics/formats/dokka-markdown.md create mode 100644 docs/topics/runners/dokka-cli.md create mode 100644 docs/topics/runners/dokka-gradle.md create mode 100644 docs/topics/runners/dokka-maven.md create mode 100644 docs/vars.list create mode 100644 mkdocs/build.gradle.kts create mode 100644 mkdocs/src/doc/docs/community/plugins-list.md create mode 100644 mkdocs/src/doc/docs/community/slack.md create mode 100644 mkdocs/src/doc/docs/developer_guide/architecture/architecture_overview.md create mode 100644 mkdocs/src/doc/docs/developer_guide/architecture/data_model/documentables.md create mode 100644 mkdocs/src/doc/docs/developer_guide/architecture/data_model/extra.md create mode 100644 mkdocs/src/doc/docs/developer_guide/architecture/data_model/page_content.md create mode 100644 mkdocs/src/doc/docs/developer_guide/architecture/extension_points/base_extensions.md create mode 100644 mkdocs/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md create mode 100644 mkdocs/src/doc/docs/developer_guide/architecture/extension_points/introduction.md create mode 100644 mkdocs/src/doc/docs/developer_guide/introduction.md create mode 100644 mkdocs/src/doc/docs/developer_guide/plugin-development/introduction.md create mode 100644 mkdocs/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md create mode 100644 mkdocs/src/doc/docs/developer_guide/workflow.md create mode 100644 mkdocs/src/doc/docs/dokka_colors.css create mode 100644 mkdocs/src/doc/docs/faq.md create mode 100755 mkdocs/src/doc/docs/favicon.svg create mode 100644 mkdocs/src/doc/docs/images/mathjax_demo.png create mode 100644 mkdocs/src/doc/docs/images/mermaid_demo.png create mode 100644 mkdocs/src/doc/docs/index.md create mode 100644 mkdocs/src/doc/docs/survey_banner.js create mode 100644 mkdocs/src/doc/docs/user_guide/applying/cli.md create mode 100644 mkdocs/src/doc/docs/user_guide/applying/gradle.md create mode 100644 mkdocs/src/doc/docs/user_guide/applying/maven.md create mode 100644 mkdocs/src/doc/docs/user_guide/introduction.md create mode 100644 mkdocs/src/doc/docs/user_guide/output-formats/html.md create mode 100644 mkdocs/src/doc/docs/user_guide/plugins/android-plugin.md create mode 100644 mkdocs/src/doc/docs/user_guide/plugins/versioning-plugin.md create mode 100644 mkdocs/src/doc/mkdocs.yml create mode 100644 runners/cli/src/main/kotlin/org/jetbrains/dokka/CliArgumentTypes.kt create mode 100644 runners/cli/src/main/kotlin/org/jetbrains/dokka/GlobalArguments.kt create mode 100644 runners/cli/src/main/kotlin/org/jetbrains/dokka/LinkMapper.kt create mode 100644 runners/cli/src/main/kotlin/org/jetbrains/dokka/PackageOptionsParser.kt create mode 100644 runners/cli/src/main/kotlin/org/jetbrains/dokka/SourceSetArgumentsParser.kt create mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaSourceSetMapper.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/toDokkaSourceSetImpl.kt create mode 100644 runners/maven-plugin/src/main/kotlin/ExternalDocumentationLinkBuilder.kt create mode 100644 runners/maven-plugin/src/main/kotlin/PackageOptions.kt create mode 100644 runners/maven-plugin/src/main/kotlin/SourceLinkMapItem.kt 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): List = 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 = 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 = setOf(DokkaConfiguration.Visibility.PUBLIC) - const val sourceSetDisplayName = "JVM" - const val sourceSetName = "main" - val moduleVersion: String? = null val pluginsConfiguration = mutableListOf() - 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?, 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, + override val documentedVisibilities: Set, // 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/build.gradle.kts b/docs/build.gradle.kts deleted file mode 100644 index 1a93d550..00000000 --- a/docs/build.gradle.kts +++ /dev/null @@ -1,3 +0,0 @@ -plugins { - id("ru.vyarus.mkdocs") version "2.3.0" -} 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 @@ + + + + + true + https://github.com/Kotlin/dokka/edit/master/docs/ + true + + + 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 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/images/dokkaHtmlCollector-example.png b/docs/images/dokkaHtmlCollector-example.png new file mode 100644 index 00000000..5bd74d8d Binary files /dev/null and b/docs/images/dokkaHtmlCollector-example.png differ diff --git a/docs/images/dokkaHtmlMultiModule-example.png b/docs/images/dokkaHtmlMultiModule-example.png new file mode 100644 index 00000000..f5091f56 Binary files /dev/null and b/docs/images/dokkaHtmlMultiModule-example.png differ diff --git a/docs/images/javadoc-format-example.png b/docs/images/javadoc-format-example.png new file mode 100644 index 00000000..45ac585c Binary files /dev/null and b/docs/images/javadoc-format-example.png differ diff --git a/docs/images/versioning-plugin-example.png b/docs/images/versioning-plugin-example.png new file mode 100644 index 00000000..cd02c558 Binary files /dev/null and b/docs/images/versioning-plugin-example.png differ diff --git a/docs/project.ihp b/docs/project.ihp new file mode 100644 index 00000000..f9ab9b9e --- /dev/null +++ b/docs/project.ihp @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/docs/src/doc/docs/community/plugins-list.md b/docs/src/doc/docs/community/plugins-list.md deleted file mode 100644 index 6ae8ce4c..00000000 --- a/docs/src/doc/docs/community/plugins-list.md +++ /dev/null @@ -1,160 +0,0 @@ -# Dokka community plugins - -On this page you can find `Dokka` plugins which are supported by both `Dokka` maintainers and community members. - -If you want to add your plugin to this list, get in touch with maintainers via [Slack](../community/slack.md) -or `GitHub`. - -If you want to learn how to develop plugins for `Dokka`, see -[Plugin development](../developer_guide/plugin-development/introduction.md) section. - -## Output Formats - -### Javadoc (Alpha) - -Javadoc plugin adds a `Javadoc` output format that looks like Java's `Javadoc`, but it's for the most part -a lookalike, so you may experience problems if you try to use it with a tool that expects native -`Javadoc` documentation generated by `Java`. - -`Javadoc` plugin does not support multiplatform projects and does not have a multi-module task. - -`Javadoc` plugin is shipped with `Dokka`, so you can start using it right away with one of the following tasks: - -* `dokkaJavadoc` - builds `Javadoc` documentation for single-module projects or for a specific module. -* `dokkaJavadocCollector` - collects generated `Javadoc` documentation from submodules and assembles it together. - -`Javadoc` plugin has its own signature provider that essentially translates `Kotlin` signatures to `Java` ones. - -**This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to -[report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see. - -[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/javadoc) - -### GFM (Alpha) - -`GFM` plugins adds the ability to generate documentation in `GitHub flavoured Markdown` format. Supports both -multimodule and multiplatform projects, and is shipped together with `Dokka`, so you can start using it -right away with one of the following tasks: - -* `dokkaGfm` - generate documentation for a non multi-module project or one specific module. -* `dokkaGfmMultiModule` - generate documentation for a multi-module project, assemble it together and - generate navigation page/menu for all the modules. - -Example: - -___ - -//[dokka-debug-kts](#gfm)/[org.jetbrains.dokka.test](#gfm)/[MyClass](#gfm) - -#### MyClass - -[jvm] -class [MyClass](#gfm) - -KDoc that describes this class - -##### Constructors - -| | | -|---|---| -| [MyClass](#gfm) | [jvm]
fun [MyClass](#gfm)() | - -##### Functions - -| Name | Summary | -|------------------|---| -| [function](#gfm) | [jvm]
fun [function](#gfm)(): [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)
KDoc comment on top of this function | - -##### Properties - -| Name | Summary | -|---|------------------------------------------------------------------------------------------------------------------------------------------------| -| [property](#gfm) | [jvm]
val [property](#gfm): [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)
KDoc comment for a property | - -___ - -**This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to -[report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see. - -[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/gfm) - -### Jekyll (Alpha) - -`Jekyll` plugins adds the ability to generate documentation in `Jekyll flavoured Markdown` format. Supports both -multi-module and multiplatform projects, and is shipped together with `Dokka`, so you can start using it -right away with one of the following tasks: - -* `dokkaJekyll` - generate documentation for a non multi-module project or one specific module. -* `dokkaJekyllMultiModule` - generate documentation for a multi-module project, assemble it together and - generate navigation page/menu for all the modules. - -**This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to -[report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see. - -[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/jekyll) - -## Extensions - -### Mathjax - -[MathJax](https://docs.mathjax.org/) allows you to include mathematics in your web pages. `MathJax` plugin -adds the ability to render mathematics from source code comments. - -If `MathJax` plugin encounters `@usesMathJax` `KDoc` tag, it adds `MathJax.js` (ver. 2) with `config=TeX-AMS_SVG` -to generated `HTML` pages. - -Usage example: -```kotlin -/** - * Some math \(\sqrt{3x-1}+(1+x)^2\) - * - * @usesMathJax - */ -class Foo {} -``` - -Which results in: - -![Mathjax demo](../images/mathjax_demo.png){ width="400" } - -[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/mathjax) - -### Mermaid - -[Mermaid JS](https://mermaid-js.github.io/mermaid/#/) lets you create diagrams and visualizations using text and code. -`Mermaid` plugin allows rendering such diagrams and visualizations found in source code documentation. - -Usage example: -```kotlin -/** - * See the graph for more details: - * \```mermaid - * graph LR - * A[Christmas] -->|Get money| B(Go shopping) - * B --> C{Let me think} - * C -->|One| D[Laptop] - * C -->|Two| E[iPhone] - * C -->|Three| F[fa:fa-car Car] - * \``` - */ -class CompositeSubscription -``` - -Which results in: - -![Mermaid demo](../images/mermaid_demo.png){ width="700" } - -For more information and examples, see -[Html Mermaid Dokka plugin](https://github.com/glureau/dokka-mermaid) repository on GitHub. - -### Kotlin as Java - -With `Kotlin as Java` plugin applied, all `Kotlin` signatures will be rendered as `Java` signatures. - -For instance, `fun foo(bar: Bar): Baz` will be rendered as `public final Baz foo(Bar bar)`. - -`Kotlin as Java` plugin is published to maven central as a -[separate artifact](https://mvnrepository.com/artifact/org.jetbrains.dokka/kotlin-as-java-plugin): -`org.jetbrains.dokka:kotlin-as-java-plugin:1.7.20`. - -[Plugin source code on GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java) diff --git a/docs/src/doc/docs/community/slack.md b/docs/src/doc/docs/community/slack.md deleted file mode 100644 index 290d4a18..00000000 --- a/docs/src/doc/docs/community/slack.md +++ /dev/null @@ -1,7 +0,0 @@ -# Slack channel - -`Dokka` has a dedicated `#dokka` channel in the `Kotlin Community Slack`, where you can ask questions and chat -about using, customizing or contributing to `Dokka`. - -[Follow the instructions](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up) -to get an invite or [connect directly](https://kotlinlang.slack.com). diff --git a/docs/src/doc/docs/developer_guide/architecture/architecture_overview.md b/docs/src/doc/docs/developer_guide/architecture/architecture_overview.md deleted file mode 100644 index fb11f32a..00000000 --- a/docs/src/doc/docs/developer_guide/architecture/architecture_overview.md +++ /dev/null @@ -1,123 +0,0 @@ -# Architecture overview - -Normally, you would think that a tool like `Dokka` simply parses some programming language sources and generates -`HTML` pages for whatever it sees along the way, with little to no abstractions. That would be the simplest and -shortest way to implement an API documentation engine. - -However, it was clear that `Dokka` may need to generate documentation from various sources (not only `Kotlin`), that users -might request additional output formats (like `Markdown`), that users might need additional features like supporting -custom `KDoc` tags or rendering `mermaid.js` diagrams - all these things would require changing a lot of code inside -`Dokka` itself if all solutions were hardcoded. - -For this reason, `Dokka` was built from the ground up to be easily extensible and customizable by adding several layers -of abstractions to the data model, and by providing pluggable extension points, giving you the ability to introduce -selective changes on a single level. - -## Overview of data model - -Generating API documentation begins with `Input` source files (`.kts`, `.java`, etc) and ends with some `Output` files -(`.html`/`.md` pages, etc). However, to allow for extensibility and customization, several input and output independent -abstractions have been added to the data model. - -Below you can find the general pipeline of processing data gathered from sources and the explanation for each stage. - -```mermaid -flowchart TD - Input --> Documentables --> Pages --> Output -``` - -* `Input` - generalization of sources, by default `Kotlin`/`Java` sources, but could be virtually anything -* `Documentables` - unified data model that represents _any_ parsed sources as a tree, independent of the source - language. Examples of a `Documentable`: class, function, package, property, etc -* `Pages` - universal model that represents output pages (e.g a function/property page) and the content it's composed of - (lists, text, code blocks) that the users needs to see. Not to be confused with `.html` pages. Goes hand in hand - with so-called `Content` model. -* `Output` - specific output format like `HTML`/`Markdown`/`Javadoc`/etc. This is a mapping of pages/content model to - some human-readable and visual representation. For instance: - * `PageNode` is mapped as - * `.html` file for `HTML` format - * `.md` file for `Markdown` format - * `ContentList` is mapped as - * `
  • ` / `
      ` for `HTML` format - * `1.` / `*` for `Markdown` format - * `ContentCodeBlock` is mapped as - * `` or `
      ` with some CSS styles in `HTML` format
-        * Text wrapped in triple backticks for `Markdown` format
-
-    
-You, as a `Dokka` developer or a plugin writer, can use extension points to introduce selective changes to the
-model on one particular level without touching everything else. 
-
-For instance, if you wanted to make some annotation/function/class invisible in the final documentation, you would only
-need to modify the `Documentables` model by filtering undesirable members out. If you wanted to display all overloaded
-methods on the same page instead of on separate ones, you would only need to modify the `Page` model by merging multiple
-pages into one, and so on.
-
-For a deeper dive into Dokka's model with more examples and details,
-see sections about [Documentables](data_model/documentables.md) and [Page/Content](data_model/page_content.md)
-
-For an overview of existing extension points that let you transform Dokka's models, see 
-[Core extension points](extension_points/core_extensions.md) and [Base extensions](extension_points/base_extensions.md).
-
-## Overview of extension points
-
-An extension point usually represents some pluggable interface that performs an action during one of the stages of
-generating documentation. An extension is therefore an implementation of that interface which is extending the
-extension point.
-
-You can create extension points, provide your own implementations (extensions) and configure them. All of
-this is possible with Dokka's plugin/extension point API.
-
-Here's a sneak peek of the DSL:
-
-```kotlin
-class MyPlugin : DokkaPlugin() {
-    // create an extension point for other developers
-    val signatureProvider by extensionPoint()
-
-    // provide a default implementation
-    val defaultSignatureProvider by extending {
-        signatureProvider with KotlinSignatureProvider()
-    }
-
-    // register our own extension in base plugin and override its default
-    val dokkaBasePlugin by lazy { plugin() }
-    val multimoduleLocationProvider by extending {
-        (dokkaBasePlugin.locationProviderFactory
-                providing MultimoduleLocationProvider::Factory
-                override dokkaBasePlugin.locationProvider)
-    }
-}
-
-// use a registered extention, pretty much dependency injection
-class MyExtension(val context: DokkaContext) {
-    
-    val signatureProvider: SignatureProvider = context.plugin().querySingle { signatureProvider }
-
-    fun doSomething() {
-        signatureProvider.signature(..)
-    }
-}
-
-interface SignatureProvider {
-    fun signature(documentable: Documentable): List
-}
-
-class KotlinSignatureProvider : SignatureProvider {
-    override fun signature(documentable: Documentable): List = listOf()
-}
-```
-
-For a deeper dive into extensions and extension points with more examples and details, see
-[Introduction to Extensions](extension_points/introduction.md).
-
-For an overview of existing extension points, see [Core extension points](extension_points/core_extensions.md) and
-[Base extensions](extension_points/base_extensions.md).
-
-## Historical context
-
-This is a second iteration of Dokka that was built from scratch.
-
-If you want to learn more about why Dokka has been designed this way, watch this great talk by Paweł Marks:
-[New Dokka - Designed for Fearless Creativity](https://www.youtube.com/watch?v=OvFoTRhqaKg). The general principles 
-and general architecture are the same, although it may be outdated in some areas, so please double-check.
diff --git a/docs/src/doc/docs/developer_guide/architecture/data_model/documentables.md b/docs/src/doc/docs/developer_guide/architecture/data_model/documentables.md
deleted file mode 100644
index 5264553d..00000000
--- a/docs/src/doc/docs/developer_guide/architecture/data_model/documentables.md
+++ /dev/null
@@ -1,245 +0,0 @@
-# Documentables Model
-
-Documentables represent data that is parsed from sources. Think of this data model as of something that could be
-seen or produced by a compiler frontend, it's not far off from the truth.
-
-By default, documentables are parsed from `Descriptor` (for `Kotlin`)
-and [Psi](https://plugins.jetbrains.com/docs/intellij/psi.html)
-(for `Java`) models. Code-wise, you can have a look at following classes:
-
-* `DefaultDescriptorToDocumentableTranslator` - responsible for `Kotlin` -> `Documentable` mapping
-* `DefaultPsiToDocumentableTranslator` - responsible for `Java` -> `Documentable` mapping
-
-Upon creation, it's a collection of trees, each with `DModule` as root.
-
-Take some arbitrary `Kotlin` source code that is located within the same module:
-
-```kotlin
-// Package 1
-class Clazz(val property: String) {
-    fun function(parameter: String) {}
-}
-
-fun topLevelFunction() {}
-
-// Package 2
-enum class Enum { }
-
-val topLevelProperty: String
-```
-
-This would be represented roughly as the following `Documentable` tree:
-
-```mermaid
-flowchart TD
-    DModule --> firstPackage[DPackage]
-    firstPackage --> DClass
-    firstPackage --> toplevelfunction[DFunction] 
-    DClass --> DProperty
-    DClass --> DFunction
-    DFunction --> DParameter
-    DModule --> secondPackage[DPackage]
-    secondPackage --> DEnum
-    secondPackage --> secondPackageProperty[DProperty]
-```
-
-At later stages of transformation, all trees are folded into one (by `DocumentableMerger`).
-
-## Documentable
-
-The main building block of documentables model is `Documentable` class. It's the base class for all more specific types
-that represent elements of parsed sources with mostly self-explanatory names (`DFunction`, `DPackage`, `DProperty`, etc)
-.
-`DClasslike` is the base class for class-like documentables such as `DClass`, `DEnum`, `DAnnotation`, etc.
-
-The contents of each documentable normally represent what you would see in source code. For instance, if you open
-`DClass`, you should find that it contains references to functions, properties, companion object, constructors and so
-on.
-`DEnum` should have references to enum entries, and `DPackage` can have references to both classlikes and top-level
-functions and properties (`Kotlin`-specific).
-
-Here's an example of a documentable:
-
-```kotlin
-data class DClass(
-    val dri: DRI,
-    val name: String,
-    val constructors: List,
-    val functions: List,
-    val properties: List,
-    val classlikes: List,
-    val sources: SourceSetDependent,
-    val visibility: SourceSetDependent,
-    val companion: DObject?,
-    val generics: List,
-    val supertypes: SourceSetDependent>,
-    val documentation: SourceSetDependent,
-    val expectPresentInSet: DokkaSourceSet?,
-    val modifier: SourceSetDependent,
-    val sourceSets: Set,
-    val isExpectActual: Boolean,
-    val extra: PropertyContainer = PropertyContainer.empty()
-) : DClasslike(), WithAbstraction, WithCompanion, WithConstructors,
-    WithGenerics, WithSupertypes, WithExtraProperties
-```
-
-___
-
-There are three non-documentable classes that important for this model:
-
-* `DRI`
-* `SourceSetDependent`
-* `ExtraProperty`.
-
-### DRI
-
-`DRI` stans for _Dokka Resource Identifier_ - a unique value that identifies a specific `Documentable`.
-All references and relations between documentables (other than direct ownership) are described using `DRI`.
-
-For example, `DFunction` with a parameter of type `Foo` has only `Foo`'s `DRI`, not the actual reference
-to `Foo`'s `Documentable` object.
-
-#### Example
-
-For an example of how a `DRI` can look like, let's take the `limitedParallelism` function from `kotlinx.coroutines`:
-
-```kotlin
-package kotlinx.coroutines
-
-import ...
-        
-public abstract class MainCoroutineDispatcher : CoroutineDispatcher() {
-    
-    override fun limitedParallelism(parallelism: Int): CoroutineDispatcher {
-        ...
-    }
-}
-```
-
-If we were to re-create the DRI of this function in code, it would look something like this:
-
-```kotlin
-DRI(
-    packageName = "kotlinx.coroutines",
-    classNames = "MainCoroutineDispatcher",
-    callable = Callable(
-        name = "limitedParallelism",
-        receiver = null,
-        params = listOf(
-            TypeConstructor(
-                fullyQualifiedName = "kotlin.Int",
-                params = emptyList()
-            )
-        )
-    ),
-    target = PointingToDeclaration,
-    extra = null
-)
-```
-
-If you format it as `String`, it would look like this:
-
-```
-kotlinx.coroutines/MainCoroutineDispatcher/limitedParallelism/#kotlin.Int/PointingToDeclaration/
-```
-
-### SourceSetDependent
-
-`SourceSetDependent` helps handling multiplatform data by associating platform-specific data (declared with either
-`expect` or `actual` modifier) with particular 
-[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets).
-
-This comes in handy if `expect`/`actual` declarations differ. For instance, the default value for `actual` might differ
-from that declared in `expect`, or code comments written for `expect` might be different from what's written
-for `actual`.
-
-Under the hood, it's a `typealias` to a `Map`:
-
-```kotlin
-typealias SourceSetDependent = Map
-```
-
-### ExtraProperty
-
-`ExtraProperty` is used to store any additional information that falls outside of the regular model. It is highly
-recommended to use extras to provide any additional information when creating custom Dokka plugins.
-
-This element is a bit more complex, so you can read more about how to use it
-[in a separate section](extra.md).
-
-___
-
-## Documentation model
-
-Documentation model is used alongside Documentables to store data obtained by parsing
-code comments (such as `KDoc`/`Javadoc`).
-
-### DocTag
-
-`DocTag` describes a specific documentation syntax element.
-
-It's universal across source languages. For instance, DocTag `B` is the same for `**bold**` in `Kotlin` and
-`bold` in `Java`.
-
-However, some `DocTag` elements are specific to a certain language, there are many such examples for `Java`
-because it allows HTML tags inside `Javadoc` comments, some of which are simply not possible to reproduce with `Markdown`.
-
-`DocTag` elements can be deeply nested with other `DocTag` children elements.
-
-Examples:
-
-```kotlin
-data class H1(
-    override val children: List = emptyList(),
-    override val params: Map = emptyMap()
-) : DocTag()
-
-data class H2(
-    override val children: List = emptyList(),
-    override val params: Map = emptyMap()
-) : DocTag()
-
-data class Strikethrough(
-    override val children: List = emptyList(),
-    override val params: Map = emptyMap()
-) : DocTag()
-
-data class Strong(
-    override val children: List = emptyList(),
-    override val params: Map = emptyMap()
-) : DocTag()
-
-data class CodeBlock(
-    override val children: List = emptyList(),
-    override val params: Map = emptyMap()
-) : Code()
-
-```
-
-### TagWrapper
-
-`TagWrapper` describes the whole comment description or a specific comment tag.
-For example: `@see` / `@author` / `@return`.
-
-Since each such section may contain formatted text inside of it, each `TagWrapper` has `DocTag` children.
-
-```kotlin
-/**
- * @author **Ben Affleck*
- * @return nothing, except _sometimes_ it may throw an [Error]
- */
-fun foo() {}
-```
-
-### DocumentationNode
-
-`DocumentationNode` acts as a container for multiple `TagWrapper` elements for a specific `Documentable`, usually
-used like this:
-
-```kotlin
-data class DFunction(
-    ...
-    val documentation: SourceSetDependent,
-    ...
-)
-```
diff --git a/docs/src/doc/docs/developer_guide/architecture/data_model/extra.md b/docs/src/doc/docs/developer_guide/architecture/data_model/extra.md
deleted file mode 100644
index 0abbc70e..00000000
--- a/docs/src/doc/docs/developer_guide/architecture/data_model/extra.md
+++ /dev/null
@@ -1,99 +0,0 @@
-# Extra
-
-## Introduction
-
-`ExtraProperty` classes are used both by [Documentable](documentables.md) and [Content](page_content.md#content-model)
-models.
-
-Source code for `ExtraProperty`:
-
-```kotlin
-interface ExtraProperty {
-    interface Key {
-        fun mergeStrategyFor(left: T, right: T): MergeStrategy = MergeStrategy.Fail {
-            throw NotImplementedError("Property merging for $this is not implemented")
-        }
-    }
-
-    val key: Key
-}
-```
-
-To declare a new extra, you need to implement `ExtraProperty` interface. It is advised to use following pattern
-when declaring new extras:
-
-```kotlin
-data class CustomExtra(
-    [any data relevant to your extra], 
-    [any data relevant to your extra] 
-): ExtraProperty {
-    override val key: CustomExtra.Key = CustomExtra
-    companion object : CustomExtra.Key
-}
-```
-
-Merge strategy (`mergeStrategyFor` method) for extras is invoked during
-[merging](../extension_points/core_extensions.md#documentablemerger) if documentables from different 
-[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) each
-have their own `Extra` of the same type. 
-
-## PropertyContainer
-
-All extras for `ContentNode` and `Documentable` classes are stored in `PropertyContainer` class instances.
-
-```kotlin
-data class DFunction(
-    ...
-    override val extra: PropertyContainer = PropertyContainer.empty()
-    ...
-) : WithExtraProperties
-```
-
-`PropertyContainer` has a number of convenient functions for handling extras in a collection-like manner.
-
-The `C` generic class parameter limits the type of properties that can be stored in the container -  it must
-match generic `C` class parameter from `ExtraProperty` interface. This allows creating extra properties
-which can only be stored in a specific `Documentable`.
-
-## Usage example
-
-In following example we will create a `DFunction`-only property, store it and then retrieve its value:
-
-```kotlin
-data class CustomExtra(val customExtraValue: String) : ExtraProperty {
-    override val key: ExtraProperty.Key = CustomExtra
-    companion object: ExtraProperty.Key
-}
-
-fun DFunction.withCustomExtraProperty(data: String): DFunction {
-    return this.copy(
-        extra = extra + CustomExtra(data)
-    )
-}
-
-fun DFunction.getCustomExtraPropertyValue(): String? {
-    return this.extra[CustomExtra]?.customExtraValue
-}
-```
-
-___
-
-You can also use extras as markers, without storing any data in them:
-
-```kotlin
-
-object MarkerExtra : ExtraProperty, ExtraProperty.Key {
-    override val key: ExtraProperty.Key = this
-}
-
-fun Documentable.markIfFunction(): Documentable {
-    return when(this) {
-        is DFunction -> this.copy(extra = extra + MarkerExtra)
-        else -> this
-    }
-}
-
-fun WithExtraProperties.isMarked(): Boolean {
-    return this.extra[MarkerExtra] != null
-}
-```
diff --git a/docs/src/doc/docs/developer_guide/architecture/data_model/page_content.md b/docs/src/doc/docs/developer_guide/architecture/data_model/page_content.md
deleted file mode 100644
index 54ded235..00000000
--- a/docs/src/doc/docs/developer_guide/architecture/data_model/page_content.md
+++ /dev/null
@@ -1,140 +0,0 @@
-# Page / Content Model
-
-Even though `Page` and `Content` models reside on the same level (under `Page`), it's easier to view it as two different
-models altogether, even though `Content` is only used in conjunction with and inside `Page` model.
-
-## Page
-
-Page model represents the structure of documentation pages to be generated. During rendering, each page
-is processed separately, so one page corresponds to exactly one output file.
-
-Page model is independent of the final output format, in other words it's universal. Which extension the pages
-should be created as (`.html`, `.md`, etc) and how is up to the `Renderer`.
-
-Subclasses of `PageNode` represent different kinds of rendered pages, such as `ModulePage`, `PackagePage`,
-`ClasslikePage`, `MemberPage` (properties, functions), etc.
-
-The Page Model is a tree structure, with `RootPageNode` at the root.
-
-Here's an example of how an arbitrary `Page` tree might look like for a module with 3 packages, one of which contains
-a top level function, top level property and a class, inside which there's a function and a property:
-
-```mermaid
-flowchart TD
-    RootPageNode --> firstPackage[PackagePageNode]
-    RootPageNode --> secondPackage[PackagePageNode]
-    RootPageNode --> thirdPackage[PackagePageNode]
-    firstPackage --> firstPackageFirstMember[MemberPageNode - Function]
-    firstPackage --> firstPackageSecondMember[MemberPageNode - Property]
-    firstPackage ---> firstPackageClasslike[ClasslikePageNode - Class]
-    firstPackageClasslike --> firstPackageClasslikeFirstMember[MemberPageNode - Function]
-    firstPackageClasslike --> firstPackageClasslikeSecondMember[MemberPageNode - Property]
-    secondPackage --> etcOne[...]
-    thirdPackage --> etcTwo[...]
-```
-
-Almost all pages are derivatives of `ContentPage` - it's the type of `Page` that has `Content` on it.
-
-## Content Model
-
-Content model describes how the actual `Page` content is presented. The important thing to understand is that it's
-also output-format independent and is universal.
-
-Content model is essentially a set of building blocks that you can put together to represent some content.
-Have a look at subclasses of `ContentNode`: `ContentText`, `ContentList`, `ContentTable`, `ContentCodeBlock`, 
-`ContentHeader` and so on. You can group content together with `ContentGroup` - for instance,
-to wrap all children with some style.
-
-```kotlin
-// real example of composing content using `DocumentableContentBuilder` DSL
-orderedList {
-    item {
-        text("This list contains a nested table:")
-        table {
-            header {
-                text("Col1")
-                text("Col2")
-            }
-            row {
-                text("Text1")
-                text("Text2")
-            }
-        }
-    }
-    item {
-        group(styles = setOf(TextStyle.Bold)) {
-            text("This is bald")
-            text("This is also bald")
-        }
-    }
-}
-```
-
-It is then responsibility of `Renderer` (i.e specific output format) to render it the way it wants. 
-
-For instance, `HtmlRenderer` might render `ContentCodeBlock` as `text`, but `CommonmarkRenderer` might 
-render it using backticks.
-
-___
-
-### DCI
-
-Each node is identified by unique `DCI`, which stands for _Dokka Content Identifier_. `DCI` aggregates `DRI`s of all
-`Documentables` that make up a specific `ContentNode`.
-
-```kotlin
-data class DCI(val dri: Set, val kind: Kind)
-```
-
-All references to other nodes (other than direct ownership) are described using `DCI`.
-
-### ContentKind
-
-`ContentKind` represents a grouping of content of one kind that can can be rendered as part of a composite
-page (one tab/block within a class's page, for instance).
-
-For instance, on the same page that describes a class you can have multiple sections (== `ContentKind`).
-One to describe functions, one to describe properties, another one to describe constructors and so on.
-
-### Styles
-
-Each `ContentNode` has `styles` property in case you want to incidate to `Renderer` that this content needs to be
-displayed in a certain way.
-
-```kotlin
-group(styles = setOf(TextStyle.Paragraph)) {
-    text("Text1", styles = setOf(TextStyle.Bold))
-    text("Text2", styles = setOf(TextStyle.Italic))
-}
-```
-
-It is then responsibility of `Renderer` (i.e specific output format) to render it the way it wants. For instance,
-`HtmlRenderer` might render `TextStyle.Bold` as `text`, but `CommonmarkRenderer` might render it as `**text**`.
-
-There's a number of existing styles that you can use, most of them are supported by `HtmlRenderer` out of the box:
-
-```kotlin
-// for code highlighting
-enum class TokenStyle : Style {
-    Keyword, Punctuation, Function, Operator, Annotation,
-    Number, String, Boolean, Constant, Builtin, ...
-}
-
-enum class TextStyle : Style {
-    Bold, Italic, Strong, Strikethrough, Paragraph, ...
-}
-
-enum class ContentStyle : Style {
-    TabbedContent, RunnableSample, Wrapped, Indented, ...
-}
-```
-
-### Extra
-
-`ExtraProperty` is used to store any additional information that falls outside of the regular model. It is highly
-recommended to use extras to provide any additional information when creating custom Dokka plugins.
-
-All `ExtraProperty` elements from `Documentable` model are propagated into `Content` model and are available
-for `Renderer`.
-
-This element is a bit complex, so you can read more about how to use it [in a separate section](extra.md).
diff --git a/docs/src/doc/docs/developer_guide/architecture/extension_points/base_extensions.md b/docs/src/doc/docs/developer_guide/architecture/extension_points/base_extensions.md
deleted file mode 100644
index 16a52fab..00000000
--- a/docs/src/doc/docs/developer_guide/architecture/extension_points/base_extensions.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# Base extensions
-
-`DokkaBase` class is a base plugin which defines a number of default implementations for `CoreExtensions` as well as
-declares its own, more high-level extension points to be used from other plugins and output formats.
-
-It's very convenient to use extension points and defaults defined in `DokkaBase` if you have an idea for a simple
-plugin that only needs to provide a few extensions or change a single extension point and have everything else be the
-default.
-
-`DokkaBase` is used extensively for Dokka's own output formats such as `HTML`, `Markdown`, `Mathjax` and others.
-
-You can learn how to add/use/override/configure extensions and extension points in
-[Introduction to Extensions](introduction.md), all the information is applicable to `DokkaBase` plugin as well.
diff --git a/docs/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md b/docs/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md
deleted file mode 100644
index 381a9596..00000000
--- a/docs/src/doc/docs/developer_guide/architecture/extension_points/core_extensions.md
+++ /dev/null
@@ -1,151 +0,0 @@
-# Core extension points
-
-Core extension points represent the main stages of generating documentation. 
-
-These extension points are plugin and output format independent, meaning it's the very core functionality and as
-low-level as can get. For higher-level extension functions that can be used in different output formats, have a look at
-[Base extensions](base_extensions.md) defined in `DokkaBase`.
-
-You can find all core extensions in `CoreExtensions` class:
-```kotlin
-object CoreExtensions {
-    val preGenerationCheck by coreExtensionPoint()
-    val generation by coreExtensionPoint()
-    val sourceToDocumentableTranslator by coreExtensionPoint()
-    val documentableMerger by coreExtensionPoint()
-    val documentableTransformer by coreExtensionPoint()
-    val documentableToPageTranslator by coreExtensionPoint()
-    val pageTransformer by coreExtensionPoint()
-    val renderer by coreExtensionPoint()
-    val postActions by coreExtensionPoint()
-}
-```
-
-On this page we'll go over each extension point individually.
-
-## PreGenerationChecker
-
-`PreGenerationChecker` can be used to run some checks and constraints. 
-
-For instance, `Javadoc` plugin does not support generating documentation for multi-platform projects, so it uses
-`PreGenerationChecker` to check for multi-platform
-[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) and fails if it finds any.
-
-## Generation
-
-`Generation` is responsible for generating documentation as a whole, utilizing other extension points where applicable.
-
-There are two implementations at the moment:
-
-* `AllModulesPageGeneration` - generates multimodule documentation, for instance when `dokkaHtmlMultiModule` task is
-  invoked.
-* `SingleModuleGeneration` - generates documentation for a single module, for instance when `dokkaHtml` task is invoked
-
-### AllModulesPageGeneration
-
-`AllModulesPageGeneration` utilizes output generated by `SingleModuleGeneration`. Under the hood it just collects all
-pages generated for individual modules and assembles everything together, creating navigation pages between the
-modules and so on.
-
-### SingleModuleGeneration stages
-
-When developing a feature or a plugin, it's more convenient to think that you are generating documentation for single
-module projects, believing that Dokka will somehow take care of the rest in multimodule environment.
-
-`SingleModuleGeneration` is at heart of generating documentation and utilizes other core extension points, so
-it's worth going over its stages. 
-
-Below you can see the transformations of [Dokka's models](../architecture_overview.md#overview-of-data-model) and 
-extension interfaces responsible for each one. Notice how `Documentables` and `Pages` are transformed multiple times.
-
-```mermaid
-flowchart TD
-    Input -- SourceToDocumentableTranslator --> doc1[Documentables]
-    subgraph documentables [ ]
-    doc1 -- PreMergeDocumentableTransformer --> doc2[Documentables]
-    doc2 -- DocumentableMerger --> doc3[Documentables]
-    doc3 -- DocumentableTransformer --> doc4[Documentables]
-    end
-    doc4 -- DocumentableToPageTranslator --> page1[Pages]
-    subgraph ide2 [ ]
-    page1 -- PageTransformer --> page2[Pages]
-    end
-    page2 -- Renderer --> Output
-```
-
-#### SourceToDocumentableTranslator
-
-`SourceToDocumentableTranslator` translates sources into documentable model. 
-
-`Kotlin` and `Java` sources are supported by default, but you can analyze any language as long as you can map
-it to the [Documentable](../data_model/documentables.md) model.
-
-For reference, see
-
-* `DefaultDescriptorToDocumentableTranslator` for `Kotlin` sources translation
-* `DefaultPsiToDocumentableTranslator` for `Java` sources translation
-
-#### PreMergeDocumentableTransformer
-
-This extension point actually comes from `DokkaBase` and is not a core extension point, but it's used in
-`SingleModuleGeneration` nonetheless. If you are implementing your own plugin without relying on `DokkaBase`,
-you can either introduce a similar extension point or rely on [DocumentableTransformer](#documentabletransformer) which
-will be discussed below.
-
-`PreMergeDocumentableTransformer` allows applying any transformation to 
-[Documentables model](../data_model/documentables.md) before different 
-[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) are merged. 
-
-Useful if you want to filter/map existing documentables. For instance, if you want to exclude members annotated with
-`@Internal`, you most likely need an implementation of `PreMergeDocumentableTransformer`.
-
-For simple condition-based filtering