Configuration

This project takes the form of a Gradle plugin which extracts information using Dokka then embeds it into a Material for MkDocs site.

Creating the project

First, you will need to create a Material for MkDocs site (or you may use an existing one) that is in the same repository as the Gradle build which you want to extract documentation from.

We recommend putting the Material for MkDocs site in a child directory of the main Gradle build (settings.gradle or settings.gradle.kts), instead of putting it into the same directory.

For example, you may have a setup similar to this:

your-project/
    docs/
        docs/
            index.md
        mkdocs.yml
    src/
        main/java/…
    build.gradle.kts
    settings.gradle.kts

You will also need to configure Dokka for your project. You can follow the official documentation and use any of the official formats to test your configuration (e.g. the HTML format). However, note that only Dokka in 2.0 mode is compatible.

Configuring Gradle

Locate the mkdocs.yml file. In the same directory, create a build.gradle.kts file:

build.gradle.kts in the same folder as mkdocs.yml

id("dev.opensavvy.dokka-mkdocs") version "VERSION HERE" //(1)!

dependencies {
    // Embeds the documentation from project :foo-bar
    dokka(project("foo-bar"))
}

1. Latest version:
   All versions: Release list

Each Gradle project that you want to include in the website should be added to the dependencies block. You may include as many projects as you want.

Each project mentioned needs to be configured to generate documentation with Dokka, see the Dokka documentation for more information. If you can see the documentation from the project in another format (e.g. Dokka HTML), it is configured properly.

Projects that are not mentioned in the dependencies block do not need to be configured to use Dokka.

Don't forget to include the project you created into your Gradle build:

Root settings.gradle.kts

// Everything else…

include("docs") // or whatever other path you used

Configuring Material for MkDocs

The Gradle plugin will generate Markdown files in docs/api. You should probably add this directory to .gitignore, as it will change quite often.

Material for MkDocs requires that all pages are added to the nav section of the main mkdocs.yml file. It is not currently possible to generate entries in another file, so the Gradle plugin must edit the mkdocs.yml file itself.

To decide where you want the plugins to generate files, you must add the following marker comments:

mkdocs.yml

# Everything else…

use_directory_urls: false #(1)!

nav:
  - Home: # your existing pages…
      - index.md
      - setup.md

  - Another: another.md # your existing pages…

# !!! EMBEDDED DOKKA START, DO NOT COMMIT !!! #
# !!! EMBEDDED DOKKA END, DO NOT COMMIT !!! #

  - Whatever: whatever.md # your existing pages…

1. Disabling use_directory_urls is currently necessary for links to be generated correctly.

When ran, the Gradle plugin will insert all pages generated by Dokka between both marker comments, overwriting anything that was previously there. The rest of the file will not be modified.

At the moment, this plugin is only able to generate pages at the top-level.

Running

Once all this configuration is done, you may run the plugin to generate the website. Assuming you have configured your Material for MkDocs website in the docs folder, run:

./gradlew docs:embedDokkaIntoMkDocs

This will populate the docs/api folder with the classes, functions… extracted from the Kotlin and Java code of the imported projects, and will add each pages to the mkdocs.yml file.

Once this is done, you may run and open your Material for MkDocs site in the same way you usually do.

Additionally, if you want the site to update when you edit source code, add the --continuous Gradle flag:

./gradlew docs:embedDokkaIntoMkDocs --continuous

That's it! Your project is now configured to embed Kotlin and Java documentation comments into a Material for MkDocs website.