Disable Kotlin Playground for `@sample` rendering by default

[IgnatBeresnev]

Problem

Embedded Kotlin Playground scripts are used to render the code referenced by the @sample KDoc tag. It works wonderfully for Kotlin's own standard and popular libraries, such as stdlib and kotlinx.coroutines, because they are included as dependencies by default.

However, you cannot simply add external dependencies to Kotlin Playground scripts - to do that, you have to fork the playground repo, add dependencies manually, and then host the playground yourself.

This means that in most cases the user code cannot be run by the playground, because external types are used in the samples, and they cannot be resolved by default.

Solution

Do not use Kotlin Playground to render @sample content by default. Instead, embed the code referenced in @sample as non-runnable code blocks. Support for Kotlin Playground runnable samples should be extracted into a separate plugin with its own settings.

Definition of Done

• SamplesTransformer and relevant code should be extracted into a separate plugin.
• Users should be able to provide their own kotlin-playground JS script (now hardcoded)
• If the default script is used, it should be possible to specify a custom playground server URL (now hardcoded to play.kotlinlang.org in the JS script)
• This plugin should replace default non-runnable code blocks with interactive and runnable Kotlin Playground samples.

---

As part of this issue, it's expected that some refactoring of DefaultSamplesTransformer will occur and that the tests for it will be revised (either new ones added or old ones checked)

---

Related: #1281

[IgnatBeresnev]

As part of the overall improvement of handling samples, it would be nice to add a user-friendly log message if the @sample link is not resolved (API returns null), with the place where this link came from.

That is, given the following code

package com.example

class MyClass {
    /*
     * @sample com.example.samples.sampleFunction
     */
    fun foo() {}
}

if com.example.samples.sampleFunction cannot be resolved, there should be a log message along the lines of "The sample link used in com.example.MyClass.foo could not be resolved. Please, make sure it points to ..."

[aajtodd]

Any idea when this will be integrated? It would definitely be nice to disable this. All of the samples we plan to include are not usable in the playground due to the external dependencies factor but also due to authentication requirements.

[IgnatBeresnev]

We'll try to prioritise this issue and ship it in Dokka 2.0.0