Is there any way to make a gradle platform project...

# dokka

[Wesley Hartford]

Is there any way to make a gradle platform project show up in dokka docs? I have a multi project build with one subproject being a gradle platform using the java platform plugin (https://docs.gradle.org/current/userguide/java_platform_plugin.html). There is no source code in this project other than the build.gradle.kts file. I'm generating documentation for the root project and all child projects using the dokkaHtmlMultiModule task, but the platform project does not show up in the resulting documentation. What I'd like to see is simply the project's Module.md file rendered into the docs as it is for other projects.

[Wesley Hartford]

I tried applying the kotlin plugin to the platform project, but my build failed because it conflicts with the java platform plugin which is required.

[Oleg Yukhnevich]

Hey
Yes, I think, that kotlin + java-platform plugins can be not compatible
And if there is no kotlin plugin, there will be no sourceSets in dokka plugin (and so no documentation is generated)
So you can try to add custom dokka sourceSet to tasks, and include Module.md there
Something like this:

plugins {
  id(java-platform")
  id("org.jetbrains.dokka")
}
tasks.withType<AbstractDokkaTask>().configureEach {
  dokkaSourceSets.register("main") {
    // configuration goes here
    include.from("Module.md")
  }
}

May be there will be needed some additional configuration inside (as there could be no defaults for some values), but overall, this should work I beleive
I think, that's because this project don'

[Wesley Hartford]

Thanks for the suggestion. It looks like AbstractDokkaTask doesn't have a dokkaSourceSets, but AbstractDokkaLeafTask does. That's a big help in other areas since I've been configuring DokkaTask and DokkaTaskPartial separatly.
Unfortunately, adding that configuration did not end up generating any content. My platform project still does not show up under All modules, and the platform/build/dokka/htmlPartial directory gets created but is empty. Do you have any further configuration suggestions?

[Oleg Yukhnevich]

yeah, wrong task name, sorry 🙂
Could you check is there some logs in Gradle regarding execution of Dokka tasks?
May be it needs at least some sources to be able to run...

[Wesley Hartford]

The logs from that task:

> Task :platform:dokkaHtmlPartial
Initializing plugins
Dokka is performing: documentation for platform
Validity check
Creating documentation models
Transforming documentation model before merging
Merging documentation models
Exiting Generation: Nothing to document

[Oleg Yukhnevich]

Exiting Generation: Nothing to document

yeah, looks like if there is no files, there will be empty output
So, next thing you can try is to create an empty file, like stub.kt and add it location to sourceSet:
f.e. put stub.kt into kotlin-stub-src dir there (or could be generated and placed in build to not pollute the project) and configure path

dokkaSourceSets.register("main") {
  sourceRoots.from("kotlin-stub-src") // or `from("build/kotlin-stub-src")
  include.from("Module.md")
}

may be this will work 🙂

[Wesley Hartford]

Yeah, this basically worked. I ended up having to put a public constant in the stub file. If the file was empty or only had something private in it, I got the same Nothing to document output. It's kind of ugly having an unnecessary element documented, but the documentation for the module is important enough to overlook that. Thanks a lot for all your help.

[Oleg Yukhnevich]

I understand, though, Dokka is API documentation engine , not just documentation engine so this is not directly Dokka responsibility IMO. But I understand that sometimes it could be useful to just embed everything there.

BTW, Have you tried something like mkdocs? https://squidfunk.github.io/mkdocs-material/
With rather easy setup it's possible to generate documentation not only for API reference + having same Module.md file rendered both in API reference and on website.
Example (opinionated, as it's mine):
• root: https://whyoleg.github.io/cryptography-kotlin/
• api reference: https://whyoleg.github.io/cryptography-kotlin/api/ (via Dokka)
• BOM module documentation: https://whyoleg.github.io/cryptography-kotlin/bom/
• documentation for openssl module (same file is used for both pages):
◦ on website: https://whyoleg.github.io/cryptography-kotlin/modules/cryptography-provider-openssl3/
◦ in api reference: https://whyoleg.github.io/cryptography-kotlin/api/cryptography-provider-openssl3-api/index.html

[Wesley Hartford]

Thanks for those links. My next step for this project will be to that type of documentation. I agree that this documentation for the platform is not really in dokka's scope.