Automatic detection of sources for apidocs generation plugins

[DanySK]

Currently, the source folders to be fed to Dokka (or other documentation tools) must be explicitly added to the project configuration. What I end up doing for rich projects is creating a second config.yml with no folder, and push them in via gradle with a specific task:

val orchidSeedSources = "orchidSeedSources"
tasks.register(orchidSeedSources) {
    doLast {
        val configFolder = listOf(projectDir.toString(), "src", "orchid", "resources")
            .joinToString(separator = File.separator)
        val baseConfig = file("$configFolder${File.separator}config-origin.yml").readText()
        val finalConfig = file("$configFolder${File.separator}config.yml")
        if (!baseConfig.contains("kotlindoc:")) {
            val sourceFolders = allprojects.asSequence()
                .flatMap { it.sourceSets["main"].allSource.srcDirs.asSequence() }
                .map { it.toString().replace("$projectDir/", "../../../") }
                .map { "\n    - '$it'" }
                .joinToString(separator = "")
            val ktdocConfiguration = baseConfig + "\n" + """
                kotlindoc:
                  menu:
                    - type: "kotlindocClassLinks"
                      includeItems: true
                  pages:
                    extraCss:
                      - 'assets/css/orchidKotlindoc.scss'
                  sourceDirs:
            """.trimIndent() + sourceFolders + "\n"
            finalConfig.writeText(ktdocConfiguration)
        }
    }
}
tasks.orchidClasses.orNull!!.dependsOn(tasks.getByName(orchidSeedSources))

I believe it could be possible to instruct the plugins to fetch the source folders automatically, and provide an option to enable the feature (or disable it, to me it would make sense to have the automatic detection enabled by default).

[cjbrooks12]

Yeah, this is something I've been giving a lot of thought to lately. It looks like what you've got with that custom task is, unfortunately, about the best that could be done for doing this automatically, at this point.

Overall, Orchid just doesn't really can't do docs based on multiple modules, but it does really need to. I've been taking small steps in this direction, and issue #232 is the first step towards really getting this solved.

I really don't know what this will look like, and I would very much appreciate any suggestions you have for how this would work from a user's perspective. One of the bigger blockers in getting automatic module detection is: how to make it work either independently of Maven/Gradle, or how to create adapters for both Maven/Gradle. In addition, something else to keep in mind, is what would support for other languages look? A long-term goal of mine is to eventually support docs for other popular languages like JS, Ruby, Python, and the solution to source-detection should ideally be able to be easily adapted to those other languages/build tools as well.

Anyway, these are just some of my initial thoughts on this, but I would greatly appreciate any suggestions or concerns from anyone with how this would work!

[DanySK]

An automatic source detection system might do the following:

• roll to the begin of the git repository, if any, otherwise, start from the current location (or, any "root detection", including specifying a folder manually)
• scan every file with the expected extension
• extract package/namespace information
• deduce the source root locations

It can be adapted to any language by changing the namespace extraction algorithm (a standard application of the Strategy design pattern should suffice).

[cjbrooks12]

I like that plan, I think it would work really great. And by trying to infer the source root from the code itself, it should work regardless of the build tool configurations.

How would you feel about making a proof-of-concept for this? The copper-leaf/dokka-json project is where this would need to end up.