Multi Module documentation, requires README.md, and includes of file with duplicate content.

[KotlinIsland]

If you want to document a module within a multi module project, you have to add a README.md file to each module, but also add and includes a modules.md file with the same(presumably) content for it to be included in the non-modules doc view:

This seems a little redundant, messy and inconsistent.

[KotlinIsland]

Maybe if multimodule, automatically add the documentation of the modules to the individual module view.

[floscher]

@KotlinIsland AFAICS it seems possible to add the module description at the very beginning of the README.md of the subprojects:

# Module ‹name of the module›

‹one paragraph of module description›

Note: If there is anything before the heading, Dokka currently throws an java.lang.IndexOutOfBoundsException: Index: 1, Size: 1 at

dokka/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationTransformer.kt

Line 47 in e8cb952

it[1].split(Regex("\n"), 2) // Matches new line after fully qualified name

Then in the Gradle build script:

tasks.withType(DokkaTask::class) {
  dokkaSourceSets {
    configureEach {
      includes = listOf("README.md", "packages.md")
    }
  }
}

---

But I don't particularly like this solution. In my opinion, Dokka should (as you suggested) rather pull the module description from the modules.md or packages.md (as described in https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation).

Then packages.md/modules.md would be files with a fixed structure from which Dokka can pull the descriptions and the developers could format the README.md however they want, without Dokka enforcing a certain formatting.

[sellmair]

@KotlinIsland: Very fair point. Agree with you.
We will probably merge #1194 first and I will try to make this easier/more intuitive afterwards!

[sellmair]

I think #1136 should also be tackled together with this.
Will start working on evaluating proposals soon.

[sellmair]

Dokka Multi-Module will not require any module description files anymore! If you specified any includes in the project, those will be automatically included ☺️

[zach-klippenstein]

Was the README issue fixed as well? I'm using version 1.4.0 and Dokka still seems to require README files in every module.

[sellmair]

This will be available in 1.4.10 ☺️ 👍