Dokka 2.0.0

[stevenzeck]

Dokka released 2.0.0 at the end of 2024, and with it, a host of changes. Most relevant for us is, it doesn't generate the documentation of Kotlin code in GitHub Flavored Markdown anymore. Only HTML and Javadoc.

• See if it can work somehow with MkDocs and mike.
• If not, determine if it track and document different versions of the toolkit.
• How to inject our own content into the documentation in addition to what it automatically generates.

[stevenzeck]

The plugin supports versioning, but it's a little different than how mike handles it. When Dokka runs, it looks for a directory defined in the versioning block: olderVersionsDir. Whatever it finds in there, it puts in a directory named older.

So the very first time you run it, without anything in olderVersionsDir, it looks like this:

// Version 1.0.0
docs/
  - index.html
  - scripts/
  - version.json

If there is something in olderVersionsDir, when Dokka runs it would look something like this:

//Version 1.5.0
docs/
  - index.html
  - scripts/
  - version.json
  - older/
    - 1.0.0/
      - index.html
      - scripts/
      - version.json

So each time Dokka runs, we'll need to copy its contents into olderVersionsDir with the version number so it's there for future use.

[stevenzeck]

As far as including markdown files in modules, yes, but it's a bit strict. For the module you want to include a markdown file in, you must add a block like this in that module's build.gradle:

dokka {
    dokkaSourceSets.configureEach {
        includes.from("lcp.md")
    }
}

And in that markdown file, it must begin with # Module {module-name}. In the case of LCP, it would be # Module readium-lcp. Anything else, and it doesn't work. We can change the module name for Dokka in gradle via moduleName.set("Readium LCP") and then the markdown would be # Module Readium LCP. It's the same deal with packages. Just replace the word "Module" with "Package".

It renders well, though it doesn't support markdown emojis.