如何在 Dokka 生成的文档中嵌入可运行的示例代码答案

【问题标题】：How do you embed runnable sample code in Dokka generated documentation如何在 Dokka 生成的文档中嵌入可运行的示例代码
【发布时间】：2021-01-31 08:09:30
【问题描述】：

我正在尝试将示例代码添加到我的 API 参考中。

我遵循此处突出显示的模式https://androidessence.com/contributing-to-kotlin 能够创建我的示例项目并运行所有代码，复制 kotlin 标准库源使用的 _sampleUtils。

我将我的模块配置为在 dokka 配置中包含示例。

tasks.dokkaHtml {
    dokkaSourceSets.configureEach {
        samples.from("$projectDir/../module-samples/test/samples/SampleFile.kt")
    }
}

示例正确加载到该函数的文档中并显示在文档中，并带有一个运行按钮。

当我点击运行时，它只是返回Unresolved reference 用于我库中的所有符号。它也无法从 _samplesUtils.kt 文件中找到 assertPrint 方法。

我在 Dokka 配置中没有看到任何其他设置，以使其包含正在记录的库的 jar 文件。

【问题讨论】：

标签： kotlin kotlin-dokka

【解决方案1】：

经过研究，我发现样本使用的是 Kotlin Playground。要添加额外的依赖项，您需要创建自己的编译器服务器。 https://github.com/AlexanderPrendota/kotlin-compiler-server.

然后使用额外的依赖项修改 build.gradle.kts 文件。

下一部分是更新 Dokka 生成的 html 以指向您的新服务器。我找不到这样做的内置方法，所以我实现了这个。

dokkaHtml {
    doLast {
        def docTree = fileTree(
                dir: "${dokkaHtml.outputDirectory.get()}",
                includes: ["**/*.html"])
        docTree.each { file ->
            def text = file.text
            file.write(text.replace(
                    '<script src="https://unpkg.com/kotlin-playground@1" data-selector="code.runnablesample"></script>',
                    '<script src="https://unpkg.com/kotlin-playground@1" data-selector="code.runnablesample" data-server="http://localhost:8080"></script>'
            ))
        }
    }
}

您还必须创建一个自定义的小 jar 来将测试代码类型和函数替换为更适合示例的代码类型和函数。

【讨论】：