Korro

Kotlin source code documentation plugin.

Inspired by kotlinx-knit.

This plugin produces code snippets into markdown documents from tests.

Setup

plugins {
    id("io.github.devcrocod.korro") version "0.0.3"
}

or

buildscript {
    dependencies {
        classpath "io.github.devcrocod:korro:0.0.3"
    }
}
                    
apply plugin: 'io.github.devcrocod.korro'

Tasks

• korro - create/update samples in documentation
• korroCheck - TODO
• korroTest - TODO

Parameters

korro {
    docs = fileTree(project.rootDir) {
        include '**/*.md'
    }

    samples = fileTree(project.rootDir) {
        include 'src/test/samples/*.kt'
    }
}

Docs

Directives are used to insert code into the documentation:

<!--- fully qualified name -->
<!---END-->

Сode will be inserted between these two directives.

Only the part between the two comments // SampleStart, // SampleEnd will be taken from the test function:

fun test() {
    ...
    // SampleStart
    sample code
    // SampleEnd
    ...
}

Note:

• Do not use function names with spaces enclosed in backticks
• Directives must always start at the beginning of the line.

Sample

build.gradle

plugins {
    id("io.github.devcrocod.korro") version "0.0.3"
}

...

korro {
    docs = fileTree(project.rootDir) {
        include 'docs/doc.md'
    }

    samples = fileTree(project.rootDir) {
        include 'src/test/samples/test.kt'
    }
}

test.kt

package samples

import org.junit.Test
import org.junit.Assert.assertEquals

class Test {
    
    @Test
    fun exampleTest() {
        val a = 1
        val b = 2
        val c: Int
        // SampleStart
        c = a + b
        // SampleEnd
        assertEquals(3, c)
    }
}

doc.md

# Docs

Some text.

Example:
<!---samples.Test.exampleTest-->
<!---END-->

Some text.

After you run korro you get the following file doc.md:

# Docs

Some text.

Example:
<!---samples.Test.exampleTest-->
```kotlin
c = a + b
``'
<!---END-->

Some text.