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

问题描述

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

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

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

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

该示例已正确加载到该函数中并通过运行按钮显示在该函数的文档中。

不过，当我点击run时，库中的所有符号都以Unresolved reference的形式返回。它还无法从_samplesUtils.kt文件中找到assertPrint方法。

在Dokka配置中，我看不到任何其他设置来使示例包含要记录的库的jar文件。

解决方法

研究后，我发现样本是在Kotlin游乐场使用的。要添加额外的依赖关系，您需要创建自己的编译器服务器。 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>'
            ))
        }
    }
}

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