diff options
Diffstat (limited to 'dokka-subprojects/plugin-jekyll')
5 files changed, 147 insertions, 0 deletions
diff --git a/dokka-subprojects/plugin-jekyll/README.md b/dokka-subprojects/plugin-jekyll/README.md new file mode 100644 index 00000000..15ad9071 --- /dev/null +++ b/dokka-subprojects/plugin-jekyll/README.md @@ -0,0 +1,17 @@ +# Jekyll plugin + +The Jekyll plugin adds the ability to generate documentation in `Jekyll Flavoured Markdown` format. It supports both +multi-module and multiplatform projects. + +The Jekyll plugin is shipped together with the Dokka Gradle Plugin, so you can start using it +right away with one of the following tasks: + +* `dokkaJekyll` - generate documentation for a single-project build or one specific module. +* `dokkaJekyllMultiModule` - generate documentation for a multi-module project, assemble it together and + generate navigation page/menu for all the modules. + +To use it with Maven or CLI runners, you have to add it as a dependency. You can find it on +[Maven Central](https://mvnrepository.com/artifact/org.jetbrains.dokka/jekyll-plugin) + +**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. diff --git a/dokka-subprojects/plugin-jekyll/api/plugin-jekyll.api b/dokka-subprojects/plugin-jekyll/api/plugin-jekyll.api new file mode 100644 index 00000000..2d75b214 --- /dev/null +++ b/dokka-subprojects/plugin-jekyll/api/plugin-jekyll.api @@ -0,0 +1,16 @@ +public final class org/jetbrains/dokka/jekyll/JekyllPlugin : org/jetbrains/dokka/plugability/DokkaPlugin { + public fun <init> ()V + public final fun getBriefCommentPreprocessor ()Lorg/jetbrains/dokka/plugability/Extension; + public final fun getJekyllPreprocessors ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; + public final fun getLocationProvider ()Lorg/jetbrains/dokka/plugability/Extension; + public final fun getPackageListCreator ()Lorg/jetbrains/dokka/plugability/Extension; + public final fun getRenderer ()Lorg/jetbrains/dokka/plugability/Extension; + public final fun getRootCreator ()Lorg/jetbrains/dokka/plugability/Extension; +} + +public final class org/jetbrains/dokka/jekyll/JekyllRenderer : org/jetbrains/dokka/gfm/renderer/CommonmarkRenderer { + public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V + public fun buildPage (Lorg/jetbrains/dokka/pages/ContentPage;Lkotlin/jvm/functions/Function2;)Ljava/lang/String; + public synthetic fun getPreprocessors ()Ljava/lang/Iterable; +} + diff --git a/dokka-subprojects/plugin-jekyll/build.gradle.kts b/dokka-subprojects/plugin-jekyll/build.gradle.kts new file mode 100644 index 00000000..1b83ba22 --- /dev/null +++ b/dokka-subprojects/plugin-jekyll/build.gradle.kts @@ -0,0 +1,24 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +import dokkabuild.overridePublicationArtifactId + +plugins { + id("dokkabuild.kotlin-jvm") + id("dokkabuild.publish-jvm") +} + +overridePublicationArtifactId("jekyll-plugin") + +dependencies { + compileOnly(projects.dokkaSubprojects.dokkaCore) + + implementation(projects.dokkaSubprojects.pluginBase) + implementation(projects.dokkaSubprojects.pluginGfm) + + implementation(kotlin("reflect")) + + testImplementation(kotlin("test")) + testImplementation(projects.dokkaSubprojects.coreTestApi) +} diff --git a/dokka-subprojects/plugin-jekyll/src/main/kotlin/org/jetbrains/dokka/jekyll/JekyllPlugin.kt b/dokka-subprojects/plugin-jekyll/src/main/kotlin/org/jetbrains/dokka/jekyll/JekyllPlugin.kt new file mode 100644 index 00000000..733c81bb --- /dev/null +++ b/dokka-subprojects/plugin-jekyll/src/main/kotlin/org/jetbrains/dokka/jekyll/JekyllPlugin.kt @@ -0,0 +1,85 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.jekyll + +import org.jetbrains.dokka.CoreExtensions +import org.jetbrains.dokka.base.DokkaBase +import org.jetbrains.dokka.base.renderers.PackageListCreator +import org.jetbrains.dokka.base.renderers.RootCreator +import org.jetbrains.dokka.base.resolvers.local.DokkaLocationProviderFactory +import org.jetbrains.dokka.base.resolvers.local.LocationProviderFactory +import org.jetbrains.dokka.base.resolvers.shared.RecognizedLinkFormat +import org.jetbrains.dokka.gfm.GfmPlugin +import org.jetbrains.dokka.gfm.renderer.BriefCommentPreprocessor +import org.jetbrains.dokka.gfm.renderer.CommonmarkRenderer +import org.jetbrains.dokka.pages.ContentPage +import org.jetbrains.dokka.plugability.* +import org.jetbrains.dokka.renderers.PostAction +import org.jetbrains.dokka.renderers.Renderer +import org.jetbrains.dokka.transformers.pages.PageTransformer + +public class JekyllPlugin : DokkaPlugin() { + + public val jekyllPreprocessors: ExtensionPoint<PageTransformer> by extensionPoint<PageTransformer>() + + private val dokkaBase by lazy { plugin<DokkaBase>() } + + private val gfmPlugin by lazy { plugin<GfmPlugin>() } + + public val renderer: Extension<Renderer, *, *> by extending { + (CoreExtensions.renderer + providing { JekyllRenderer(it) } + override plugin<GfmPlugin>().renderer) + } + + public val rootCreator: Extension<PageTransformer, *, *> by extending { + jekyllPreprocessors with RootCreator + } + + public val briefCommentPreprocessor: Extension<PageTransformer, *, *> by extending { + jekyllPreprocessors with BriefCommentPreprocessor() + } + + public val packageListCreator: Extension<PageTransformer, *, *> by extending { + jekyllPreprocessors providing { + PackageListCreator(it, RecognizedLinkFormat.DokkaJekyll) + } order { after(rootCreator) } + } + + public val locationProvider: Extension<LocationProviderFactory, *, *> by extending { + dokkaBase.locationProviderFactory providing ::DokkaLocationProviderFactory override listOf(gfmPlugin.locationProvider) + } + + internal val alphaVersionNotifier by extending { + CoreExtensions.postActions providing { ctx -> + PostAction { + ctx.logger.info( + "The Jekyll output format is still in Alpha so you may find bugs and experience migration " + + "issues when using it. You use it at your own risk." + ) + } + } + } + + @OptIn(DokkaPluginApiPreview::class) + override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement = + PluginApiPreviewAcknowledgement +} + +public class JekyllRenderer( + context: DokkaContext +) : CommonmarkRenderer(context) { + + override val preprocessors: List<PageTransformer> = context.plugin<JekyllPlugin>().query { jekyllPreprocessors } + + override fun buildPage(page: ContentPage, content: (StringBuilder, ContentPage) -> Unit): String { + val builder = StringBuilder() + builder.append("---\n") + builder.append("title: ${page.name}\n") + builder.append("---\n") + content(builder, page) + return builder.toString() + } +} diff --git a/dokka-subprojects/plugin-jekyll/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin b/dokka-subprojects/plugin-jekyll/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin new file mode 100644 index 00000000..563945eb --- /dev/null +++ b/dokka-subprojects/plugin-jekyll/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin @@ -0,0 +1,5 @@ +# +# Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. +# + +org.jetbrains.dokka.jekyll.JekyllPlugin |