Extract Kotlin Playground runnable samples into a separate plugin #4329

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

…lesConfigurationTest

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.

…ndServer to KotlinPlaygroundServer

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

vmishenev · 2025-11-17T13:33:41Z

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

+            }
+        }.transformContentPagesTree {
+            it.modified(
+                embeddedResources = it.embeddedResources + scriptsPages


This will add the JS script to every page.
I think it is a bit better to add the script only on pages containing samples, in the same way it is done for playground.min.js.

fixed, see 86af502

This is not in the same way as it is done for playground.min.js.
Is it possible to add script and style resources to a page in KotlinPlaygroundSamplesTransformer? See KotlinPlaygroundSamplesTransformer.kt:52

done, see d299198

vmishenev · 2025-11-17T13:35:01Z

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

+
+public class KotlinPlaygroundSamplesStylesInstaller(private val dokkaContext: DokkaContext) : PageTransformer {
+    private val stylesPages = listOf(
+        "styles/kotlin-playground-samples.css"


The same as the one above regarding the script.

idk where it can be reused in styles, in scripts i have refactored

You have already changed it for the stylesheets in 86af502

...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

…amples

…ndSamples`

…e` property

…s registration to extension points

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

…ages

…iptors)

…KotlinPlaygroundSamplesTransformer to internal

…ller

yuriioliinyk4 added 11 commits October 27, 2025 23:46

disable kotlin playground for samples, make samples non-runnable

b1318ef

feat: add RunnableSamplesPlugin

608f58a

feat: add playground server configuration to runnable samples

2fce8c6

test: add RunnableSamplesInstallerTest and minor enhance RunnableSamp…

df20742

…lesConfigurationTest

chore: add copyright

0509017

docs: add documentation for Runnable Samples Plugin

e46868f

integration tests: fix ExampleProjectsTest

3325836

integration tests: fix AndroidProjectIT

bd5464a

integration tests: fix KotlinMultiplatformIT

9979e06

integration tests: fix AndroidComposeIT

7cb2a8b

chore: add copyright

eea4108

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

Disable Kotlin Playground for @sample rendering by default #3041

Open

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

refactor: rename RunnableSamples to KotlinPlaygroundSamples, playgrou…

0eb934d

…ndServer to KotlinPlaygroundServer

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

6e3f6ae

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 added 4 commits November 18, 2025 19:24

docs: update README to use dokkaHtmlPlugin in examples

89d0191

refactor: reuse scriptsPages in modifyScript()

5218ddf

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

86af502

…amples

refactor: rename package kotlinplaygroundsamples to `kotlinPlaygrou…

78f2cc9

…ndSamples`

yuriioliinyk4 added 2 commits November 19, 2025 00:30

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

73c2585

…e` property

test: add tests for KotlinPlaygroundSamples transformer and installer…

24fc432

…s registration to extension points

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 4 commits November 21, 2025 13:02

refactor: remove FQN in KotlinPlaygroundSamplesPlugin and refactor us…

cd2f2b5

…ages

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

08813a2

…iptors)

refactor: change visibility of KotlinPlaygroundSamplesInstallers and …

8f60834

…KotlinPlaygroundSamplesTransformer to internal

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

d299198

…ller

Extract Kotlin Playground runnable samples into a separate plugin #4329

Are you sure you want to change the base?

Extract Kotlin Playground runnable samples into a separate plugin #4329

Uh oh!

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!

vmishenev Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

yuriioliinyk4 Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

vmishenev Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

yuriioliinyk4 Nov 21, 2025

Choose a reason for hiding this comment

Uh oh!

vmishenev Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

yuriioliinyk4 Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

vmishenev Nov 19, 2025

Choose a reason for hiding this comment

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

whyoleg commented Nov 3, 2025 •

edited

Loading