Extract Kotlin Playground runnable samples into a separate plugin #4329

yuriioliinyk4 · 2025-10-31T14:03:16Z

Copilot

Pull Request Overview

This PR introduces a new Dokka plugin called plugin-runnable-samples that makes @sample code blocks interactive and runnable using Kotlin Playground. The plugin extracts runnable samples functionality from the base plugin into a standalone, optional plugin.

Key changes:

Creates new plugin-runnable-samples module with transformer, installer, and configuration components
Removes Kotlin Playground integration from the base plugin (DefaultSamplesTransformer, styles, scripts)
Updates base plugin to use callback pattern for dark mode changes instead of directly managing Kotlin Playground
Updates integration test expectations to reflect removed Kotlin Playground script references

Reviewed Changes

Copilot reviewed 156 out of 207 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
settings.gradle.kts	Adds new plugin-runnable-samples module to build
plugin-runnable-samples/*	New plugin with transformer, installer, configuration, tests, and resources
plugin-base/*	Removes runnable samples logic, styles, and scripts; refactors dark mode handling
dokka-subprojects/README.md	Documents new plugin in project structure
integration test files	Updates expected output to remove Kotlin Playground references

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-11-03T15:01:54Z

...ain/kotlin/org/jetbrains/dokka/kotlinPlaygroundSamples/KotlinPlaygroundSamplesTransformer.kt

+    private fun createSampleBody(imports: List<String>, body: String) =
+    // takeIf {} is needed so that joinToString's postfix is not added for empty lists,
+        // and trimMargin() then removes the first empty line
+        """ |${


The comment on lines 101-102 is misaligned with the code. The opening triple-quote for the multi-line string starts on line 103, but the comment explaining trimMargin() appears on line 102, creating confusion about what the comment applies to. The comment should be moved above line 100 or reformatted to clearly explain the entire function's behavior.

whyoleg · 2025-11-03T16:07:33Z

(sorry, closed by accident)
I haven't reviewed the PR in detail yet, but I do have several high-level suggestions:

What do you think about renaming the plugin to kotlin-playground-plugin or kotlin-playground-samples-plugin? It's mostly about the fact that runnable is too generic, and might imply that this plugin will somehow run samples, such as tests, when it's really only about running them on the playground.
We should consider providing type-safe accessors for the new Dokka plugin in the Dokka Gradle plugin (as for the versioning plugin), as samples are needed in the stdlib and all kotlinx libraries, and so just copying the configuration from the Configuration example using Dokka Gradle Plugin v2 section is not really feasible.
It would be really nice to check how those changes will work on one of the kotlinx libraries before merging the PR. For me, kotlinx.io has the simplest setup for testing changes.

yuriioliinyk4 · 2025-11-05T18:05:33Z

What do you think about renaming the plugin to kotlin-playground-plugin or kotlin-playground-samples-plugin?

I have renamed plugin to kotlin-playground-samples-plugin.

We should consider providing type-safe accessors for the new Dokka plugin in the Dokka Gradle plugin

I agree, I will implement this.

It would be really nice to check how those changes will work on one of the kotlinx libraries before merging the PR.

I have checked it, seems like everything is fine, examples below

2.1.0(currently):

this PR, without plugin(by default):

this PR with applied kotlin-playground-samples-plugin(looks exactly the same as in 2.1.0):

The only thing I noticed is that the new samples without the plugin are too close to each other(see screenshot below). As for me, it’s easy to mistake them for a single sample. I’d suggest adding a bit more spacing between them. I can create an issue for this after merging this PR. What do you think?

vmishenev

Great 👍
I have some minor comments, but overall LGTM.

I would also add a unit test to check whether KotlinPlaygroundSamplesTransformer is applied.

dokka-subprojects/plugin-kotlin-playground-samples/README.md

.../main/kotlin/org.jetbrains.dokka.kotlinplaygroundsamples/KotlinPlaygroundSamplesInstaller.kt

dokka-subprojects/plugin-kotlin-playground-samples/api/plugin-kotlin-playground-samples.api

...projects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/HtmlRenderer.kt

.../main/kotlin/org.jetbrains.dokka.kotlinplaygroundsamples/KotlinPlaygroundSamplesInstaller.kt

.../main/kotlin/org/jetbrains/dokka/kotlinPlaygroundSamples/KotlinPlaygroundSamplesInstaller.kt

...n/kotlin/org.jetbrains.dokka.kotlinplaygroundsamples/KotlinPlaygroundSamplesConfiguration.kt

vmishenev · 2025-11-17T13:51:31Z

@whyoleg Would you like to review this PR? Or will merging without your review be okay?

whyoleg · 2025-11-17T13:56:44Z

@whyoleg Would you like to review this PR? Or will merging without your review be okay?

Yeah, I would like to take a look! I will do it today/tomorrow.

whyoleg

Nice!
We should probably create an issue to enable samples for kotlinx and stdlib?

@berezinant, could you please review the changes to .js/.css files (this and in plugin-kotlin-playground-samples module)?
Additionally, @berezinant, playground samples are now disabled by default. Should we still enable them in ui-showcase?

...src/main/kotlin/org/jetbrains/dokka/kotlinPlaygroundSamples/KotlinPlaygroundSamplesPlugin.kt

...src/main/kotlin/org.jetbrains.dokka.kotlinplaygroundsamples/KotlinPlaygroundSamplesPlugin.kt

dokka-subprojects/plugin-kotlin-playground-samples/build.gradle.kts

vmishenev · 2025-12-01T13:50:40Z

@yuriioliinyk4 Could you resolve the merge conflicts and update the integration tests to merge this PR?

…lesConfigurationTest

…ndServer to KotlinPlaygroundServer

…amples

…ndSamples`

…e` property

…s registration to extension points

…ages

…iptors)

…KotlinPlaygroundSamplesTransformer to internal

…ller

vmishenev linked an issue Nov 1, 2025 that may be closed by this pull request

Disable Kotlin Playground for @sample rendering by default #3041

Closed

vmishenev requested review from Copilot, vmishenev and whyoleg November 1, 2025 21:16

Copilot AI reviewed Nov 3, 2025

View reviewed changes

whyoleg closed this Nov 3, 2025

whyoleg reopened this Nov 3, 2025

vmishenev reviewed Nov 17, 2025

View reviewed changes

whyoleg approved these changes Nov 17, 2025

View reviewed changes

...src/main/kotlin/org/jetbrains/dokka/kotlinPlaygroundSamples/KotlinPlaygroundSamplesPlugin.kt Outdated Show resolved Hide resolved

...src/main/kotlin/org.jetbrains.dokka.kotlinplaygroundsamples/KotlinPlaygroundSamplesPlugin.kt Outdated Show resolved Hide resolved

yuriioliinyk4 force-pushed the yuriioliinyk4/disable-kotlin-playground-for-sample branch from 8ed1cd6 to 24fc432 Compare November 19, 2025 00:03

whyoleg reviewed Nov 19, 2025

View reviewed changes

dokka-subprojects/plugin-kotlin-playground-samples/build.gradle.kts Outdated Show resolved Hide resolved

yuriioliinyk4 added 14 commits December 2, 2025 00:06

disable kotlin playground for samples, make samples non-runnable

ec12899

feat: add RunnableSamplesPlugin

4526bfe

feat: add playground server configuration to runnable samples

9fa498e

test: add RunnableSamplesInstallerTest and minor enhance RunnableSamp…

e9bce8d

…lesConfigurationTest

chore: add copyright

3c850ca

docs: add documentation for Runnable Samples Plugin

97b36e3

integration tests: fix ExampleProjectsTest

2ff1585

integration tests: fix AndroidProjectIT

ec3d3a1

integration tests: fix KotlinMultiplatformIT

b711aaa

integration tests: fix AndroidComposeIT

b54ea7c

chore: add copyright

c95766e

refactor: rename RunnableSamples to KotlinPlaygroundSamples, playgrou…

572ef69

…ndServer to KotlinPlaygroundServer

feat: add type-safe accessors in DGP for new plugin

5452dfc

docs: update README to use dokkaHtmlPlugin in examples

cf653f4

yuriioliinyk4 added 9 commits December 2, 2025 00:12

refactor: reuse scriptsPages in modifyScript()

13078be

fix: inject KotlinPlayground resources only for pages with runnable s…

0eeb6fc

…amples

refactor: rename package kotlinplaygroundsamples to `kotlinPlaygrou…

02c39a0

…ndSamples`

refactor: replace repeated plugin<DokkaBase>() calls with `dokkaBas…

d51e9e0

…e` property

test: add tests for KotlinPlaygroundSamples transformer and installer…

083d6e5

…s registration to extension points

refactor: remove FQN in KotlinPlaygroundSamplesPlugin and refactor us…

5692b9e

…ages

build: make the analysis kotlin dependency switchable (symbols, descr…

36e79f6

…iptors)

refactor: change visibility of KotlinPlaygroundSamplesInstallers and …

727ab16

…KotlinPlaygroundSamplesTransformer to internal

refactor: inject resources into pages in transformer instead of insta…

3560a5f

…ller

yuriioliinyk4 force-pushed the yuriioliinyk4/disable-kotlin-playground-for-sample branch from d299198 to 286aeb8 Compare December 1, 2025 23:50

integration tests: fix kotlin-multiplatform-example test

ab1e065

yuriioliinyk4 force-pushed the yuriioliinyk4/disable-kotlin-playground-for-sample branch from 286aeb8 to ab1e065 Compare December 1, 2025 23:58

test: fix ContentForSamplesTest

6cd7a48

vmishenev mentioned this pull request Dec 2, 2025

Trigger tests: Extract Kotlin Playground runnable samples into a separate plugin #4379

Closed

yuriioliinyk4 added 4 commits December 4, 2025 21:55

integration tests: fix KotlinMultiplatformIT

5c8c5f1

integration tests: fix MultiplatformAndroidJvmProjectIT

8b78599

integration tests: fix AndroidKotlinMultiplatformBuiltInTest

8a7087a

refactor: change type of scriptsPages and stylesPages to String

91aa80a

vmishenev merged commit 1cd80f9 into Kotlin:master Dec 6, 2025
7 checks passed

Extract Kotlin Playground runnable samples into a separate plugin #4329

Extract Kotlin Playground runnable samples into a separate plugin #4329

Conversation

yuriioliinyk4 commented Oct 31, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Nov 3, 2025

Choose a reason for hiding this comment

Uh oh!

whyoleg commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yuriioliinyk4 commented Nov 5, 2025

Uh oh!

vmishenev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vmishenev commented Nov 17, 2025

Uh oh!

whyoleg commented Nov 17, 2025

Uh oh!

whyoleg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vmishenev commented Dec 1, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

whyoleg commented Nov 3, 2025 •

edited

Loading