https://github.com/kotools/samples

Gradle plugin that inlines read-only Kotlin and Java code samples into Dokka documentation, ensuring they are always correct and visible not only online but also in IDEs.
https://github.com/kotools/samples

dokka gradle java kotlin

Last synced: 3 months ago
JSON representation

Gradle plugin that inlines read-only Kotlin and Java code samples into Dokka documentation, ensuring they are always correct and visible not only online but also in IDEs.

Host: GitHub
URL: https://github.com/kotools/samples
Owner: kotools
License: mit
Created: 2024-09-12T18:27:35.000Z (almost 2 years ago)
Default Branch: main
Last Pushed: 2026-03-28T00:28:41.000Z (3 months ago)
Last Synced: 2026-03-28T00:29:20.054Z (3 months ago)
Topics: dokka, gradle, java, kotlin
Language: Kotlin
Homepage:
Size: 1.96 MB
Stars: 29
Watchers: 1
Forks: 0
Open Issues: 4
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md

Awesome Lists containing this project

README

          # Kotools Samples

[![Latest][kotools-samples-badge]][kotools-samples-releases]

[![Gradle][gradle-badge]][gradle]

[![Kotlin][kotlin-badge]][kotlin]

[![Java][java-badge]][java]

[![Dokka][dokka-badge]][dokka]

**Kotools Samples** is a [Gradle] plugin designed to help [Kotlin] library

authors integrate **read-only samples** into their documentation. It addresses a

limitation in [Dokka], which does not allow making code samples **non-editable**

or **non-executable**.

## ⭐️ Key Features

- **Readonly inlined code samples:** Displays your examples inlined in the

  documentation, ensuring they are non-editable and non-executable, preventing

  unwanted modification or execution.

- **Sample visibility in IDE:** Unlike many libraries (such as Jetpack Compose),

  Kotools Samples makes your examples visible within the IDE (e.g.,

  IntelliJ IDEA, Android Studio), enhancing accessibility and usability during

  development.

- **Always correct samples:** Ensures your examples are always up-to-date by

  compiling them alongside your main and test sources. Any breaking changes in

  your codebase will trigger compilation errors, prompting you to update the

  examples.

- **Kotlin/JVM support:** Fully supports the Kotlin/JVM platform, with [Kotlin]

  Multiplatform support in future releases.

- **Seamless integration:** Works effortlessly with [Kotlin] and [Dokka],

  smoothly integrating into your Gradle build process.

## 🛠️ Installation

For adding Kotools Samples to your Kotlin/JVM project, it is recommended to use

the [Gradle] plugins DSL in [Kotlin]. Just replace the `$version` variable by

the [latest version](#kotools-samples) or by another one available in the

[changelog](CHANGELOG.md).

```kotlin

plugins {

    id("org.kotools.samples") version "$version"

}

```

See [this plugin on the Gradle Plugin Portal][kotools-samples-plugin] for more

installation options.

> The `org.kotools.samples.jvm` plugin is deprecated (see

> [#42](https://github.com/kotools/samples/issues/42)).

## 🧑‍💻 Usage example

Kotools Samples ensures that your code samples are integrated into your

documentation without affecting your main sources. For doing so, it creates a

source set named `sample` dedicated for code samples.

Here's a [Kotlin] sample:

```kotlin

// File location: src/sample/kotlin/IntSample.kt

import kotlin.test.Test

class IntSample {

    @Test

    fun addition() {

        val x = 1

        val y = 2

        check(x + y == 3)

    }

}

```

Reference this sample in your [Dokka] documentation:

```kotlin

// File location: src/main/kotlin/Int.kt

/**

 * Performs an addition with [x] and [y] integers (`x + y`).

 *

 * SAMPLE: [IntSample.addition]

 */

public fun addition(x: Int, y: Int): Int = x + y

```

Here's the documentation generated by [Dokka] with Kotools Samples:

![Screenshot](projects/demonstration/screenshot.png)

## ✅ Supported constructs

Kotools Samples offers powerful features for writing expressive samples and

integrating them into the documentation.

### 🧪 Sample sources

This Gradle plugin is able to extract the body of member functions, which can be

an expression body, even from multiple classes located in the same file. In case

of empty body, it extracts a placeholder indicating that the sample is not yet

implemented.

Top-level functions being incompatible with the `@Test` annotation from Kotlin,

they are not supported. This is for ensuring that all samples are testable.

```kotlin

package samples

import kotlin.test.Test

class FirstSample {

    @Test

    fun body() {

        val x = 1

        val y = 2

        check(x + y == 3)

    }

    @Test

    fun expressionBody(): Unit = check(1 + 2 == 3)

}

class SecondSample { // Multiple classes in single file is supported.

    @Test

    fun empty() {} // Placeholder: TODO("Sample is not yet implemented.")

}

```

### 🎯 Main sources

For integrating samples into the documentation, this plugin supports KDoc

comments with one or multiple lines, containing one or more sample references.

```kotlin

/** SAMPLE: [samples.FirstSample.body] */

fun singleLineKDoc() = Unit

/**

 * SAMPLE: [samples.FirstSample.body]

 */

fun multiLineKDoc() = Unit

/**

 * SAMPLE: [samples.FirstSample.body]

 * SAMPLE: [samples.FirstSample.expressionBody]

 */

fun multipleSamples() = Unit

```

## 📝 Documentation

Here's additional documentation for learning more about this project:

- [Dependency compatibility](documentation/dependencies.md)

- [Security Policy](SECURITY.md)

## 🤝 Community

Join our thriving community! Connect, share insights, and collaborate with

fellow developers to make Kotools Samples even more powerful.

- [#kotools on Kotlin Slack](https://kotlinlang.slack.com/archives/C05H0L1LD25)

## 📣 Show Your Support

If you find this project valuable, show your support by giving us a ⭐️ on

GitHub. Your feedback and engagement mean the world to us!

## 🚧 Contributing

Contributions are welcome! Feel free to submit bug reports, feature requests, or

pull requests to improve the plugin.

## 🙏 Acknowledgements

Thanks to [Loïc Lamarque][@LVMVRQUXL] for creating and sharing this project with

the open source community.

Thanks to all the [people that ever contributed][kotools-samples-contributors]

through code or other means such as bug reports, feature suggestions and so on.

## 📄 License

This project is licensed under the [MIT License](LICENSE.txt).

[@LVMVRQUXL]: https://github.com/LVMVRQUXL

[dokka]: https://kotl.in/dokka

[dokka-badge]: https://img.shields.io/badge/Dokka-v2.0.0-blue

[gradle]: https://gradle.org

[gradle-badge]: https://img.shields.io/badge/Gradle-v8.12.1-blue?logo=gradle

[java]: https://www.java.com

[java-badge]: https://img.shields.io/badge/Java-v17-blue

[kotlin]: https://kotlinlang.org

[kotlin-badge]: https://img.shields.io/badge/Kotlin-v2.0.21-blue?logo=kotlin

[kotools-samples-badge]: https://img.shields.io/github/v/release/kotools/samples?label=Latest

[kotools-samples-contributors]: https://github.com/kotools/samples/graphs/contributors

[kotools-samples-plugin]: https://plugins.gradle.org/plugin/org.kotools.samples

[kotools-samples-releases]: https://github.com/kotools/samples/releases

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/kotools/samples

Awesome Lists containing this project

README