How does one publish documentation of the current ...

# dokka

[andylamax]

How does one publish documentation of the current and old versions of the same project??

[simon.vergauwen]

We just to do this in Arrow, but it was by manually moving the “old” version into a sub-directory and generating the new version

[andylamax]

Looks there is a plugin for this
https://github.com/Kotlin/dokka/tree/master/plugins/versioning

[simon.vergauwen]

Oh, very interesting! Thank you for sharing, will look into this.

[andylamax]

I have failed to understand the documentation of the dokka-versioning plugin to it to work. When you do, please drop some tips whenever you can

[hfhbd]

You still need to save the old docs somewhere. Otherwise it is impossible to get the old docs (except checking out old tags, build it, and store the docs).

[andylamax]

I figured that part out. I had tried setting a directory of old docs, applying the version plugin on both the root and the sub modules, but dokkaHtmlMultiModule still just produced the same version 😔.

It is likely I am missing something, But I can't seem to know what exactly

[Ignat Beresnev]

You still need to save the old docs somewhere. Otherwise it is impossible to get the old docs (except checking out old tags, build it, and store the docs).

Yeah, unfortunately - that's one of the limitation of the current implementation of the versioning plugin

There's an issue that describes the flaws of this approach in more detail, and suggests a solution: https://github.com/Kotlin/dokka/issues/2785

Consider upvoting it and/or leaving a comment if you have anything to add 🙂

[Adrian Landborn]

Sorry for jumping in here but are you guys abled to get the version dop-down showing anywhere? (I am not) everything looks exacly the same as it did before I added the versioning plugin. 🤔

[andylamax]

What you are saying @Adrian Landborn is exactly what I ended up achieving. So, I assumed I did not understand the documentation well

[Adrian Landborn]

Here is the gradle code I have.

Also not really sure if the order of the 2 “pluginConfiguration” males any difference.

val dokkaVersion: String by rootProject.extra
pluginManager.withPlugin("org.jetbrains.dokka") {
    afterEvaluate {
        this.tasks.withType(DokkaMultiModuleTask::class) {
            pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
                customAssets = listOf(file("documentation/logo-icon.svg"))
                footerMessage = "© xxx 1999-2023"
            }
            outputDirectory.set(file("documentation/html"))
            includes.from("documentation/packages.md")

            pluginConfiguration<org.jetbrains.dokka.versioning.VersioningPlugin, org.jetbrains.dokka.versioning.VersioningConfiguration> {
                version = "1.7.1"
                versionsOrdering = listOf("1.7.1","1.7.0")
                olderVersionsDir = file("documentation/version")
                olderVersions = listOf(file("documentation/version/1.7.0"))
                renderVersionsNavigationOnAllPages = true
            }
        }

        dependencies {
            "dokkaHtmlPlugin"("org.jetbrains.dokka:android-documentation-plugin:$dokkaVersion")
        }
    }
}

[Adrian Landborn]

And this is what the code looks inside one of the modules:

tasks.dokkaHtmlPartial.configure {
    moduleName.set("Module A")
    dokkaSourceSets {
        configureEach {
            jdkVersion.set(8)
            includes.from("$projectDir/README.md")
            samples.from(rootProject.file("example/components/component1/src/main/java/"))
            reportUndocumented.set(true)
            skipEmptyPackages.set(true)
        }
    }
}

[Ignat Beresnev]

@Adrian Landborn did you apply the versioning plugin itself? I only see the android plugin in your configuration

dependencies {
    dokkaHtmlPlugin("org.jetbrains.dokka:versioning-plugin:1.8.10")
}

[Ignat Beresnev]

And the versioning plugin needs to be added as a dependency like I showed above in every subproject as well as in the parent project - it's mentioned in the docs.

[Adrian Landborn]

Project:

dependencies {
    classpath("org.jetbrains.dokka:dokka-gradle-plugin:$dokkaVersion")
    classpath("org.jetbrains.dokka:dokka-base:$dokkaVersion")
    classpath("org.jetbrains.dokka:versioning-plugin:$dokkaVersion")
    
   // etc.
}

Modules:

plugins {
    id("com.android.library")
    id("kotlin-android")
    id("org.jetbrains.dokka")
}

Is there anything missing? (We’ve been using docka without versioning the last year)

[Ignat Beresnev]

It has to be dokkaHtmlPlugin(..) or dokkaPlugin(..) specifically, I believe. Not classpath(..)

[Adrian Landborn]

As mentioned everything else is working apart from the versioning plugin

[Ignat Beresnev]

oh, wait. Those would be two different dependencies blocks. You'd add the versioning plugin as a classpath dependency in the buildscript {} for the configuration classes to be available, but you also need to add it as dokkaHtmlPlugin(...) in the average dependencies {} block of your project.

[Adrian Landborn]

I have this block in every module if it was this you were referring to.

dependencies {
    implementation(project(":xxx:foundation"))

    implementation("com.google.android.material:material:$materialVersion")

    // Compose
    val composeBom = platform("androidx.compose:compose-bom:$composeBom")
    implementation(composeBom)
    implementation("androidx.compose.material:material")

    // Compose Preview
    implementation("androidx.compose.ui:ui-tooling-preview")
    debugImplementation("androidx.compose.ui:ui-tooling")
}

tasks.dokkaHtmlPartial.configure {
    moduleName.set("Design")
    dokkaSourceSets {
        configureEach {
            jdkVersion.set(8)
            includes.from("$projectDir/README.md")
            samples.from(rootProject.file("xxx/design/src/main/java/"))
            reportUndocumented.set(true)
            skipEmptyPackages.set(true)
        }
    }
}

[Adrian Landborn]

Or do you mean here?

pluginManager.withPlugin("org.jetbrains.dokka") {
    afterEvaluate {
        this.tasks.withType(DokkaMultiModuleTask::class) {
            pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
                customAssets = listOf(file("documentation/logo-icon.svg"))
                footerMessage = "xxx 1999-2023"
            }
            outputDirectory.set(file("documentation/html"))
            includes.from("documentation/packages.md")

            pluginConfiguration<org.jetbrains.dokka.versioning.VersioningPlugin, org.jetbrains.dokka.versioning.VersioningConfiguration> {
                version = "1.7.1"
                versionsOrdering = listOf("1.7.1","1.7.0")
                olderVersionsDir = file("documentation/version")
                olderVersions = listOf(file("documentation/version/1.7.0"))
                renderVersionsNavigationOnAllPages = true
            }
        }

        dependencies {
            "dokkaHtmlPlugin"("org.jetbrains.dokka:android-documentation-plugin:$dokkaVersion")

         // HERE?
        }
    }
}

[Ignat Beresnev]

So it needs to be something like that (not tested, just pseudo code)

root build.gradle.kts

subprojects {
    apply {
        plugin("org.jetbrains.dokka")
    }
    dependencies {
        dokkaHtmlPlugin("org.jetbrains.dokka:versioning-plugin:$dokkaVersion")
    }
}

or you can move the dokkaHtmlPlugin part to the actual submodules, but it needs to be applied in all of them

and then in subprojects:

buildscript {
    dependencies {
        classpath("org.jetbrains.dokka:versioning-plugin:1.8.10")
    }
}

tasks.dokkaHtmlMultiModule {
    pluginConfiguration<VersioningPlugin, VersioningConfiguration> {
        version = currentVersion
        olderVersionsDir = file(previousVersionsDirectory)
    }
}

[Ignat Beresnev]

Or do you mean here?

It's difficult to say without seeing the whole project, but if that block is applied for every subproject - yes

You should look at the example project for the versioning plugin: https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-versioning-multimodule-example

[Adrian Landborn]

Thanks for the help @Ignat Beresnev. It’s getting late here in Sweden. Will continue looking at it tomorrow.

[Adrian Landborn]

What is strange is that it says that the childProjects shuld be EMPTY which I feel is strange. https://github.com/Kotlin/dokka/blob/master/examples/gradle/dokka-versioning-multimodule-example/parentProject/childProjectA/build.gradle.kts

But maybe subprojects and modules differ…

[Ignat Beresnev]

It doesn't say that they should be empty 🙂 They just happen to be empty in that example. There's a thousand ways to do the same thing in Gradle, so it's hard to predict what configuration people have/prefer

[Adrian Landborn]

Oh, were using allprojects and not subprojects

[Adrian Landborn]

I guess we can use is similary

[Adrian Landborn]

I’ve cloned and tried out the Example projects but some things does not add up when running with an Android project. 🤔

[Adrian Landborn]

Just as a update. I managed to solve it on my end. Dont know why it didnt work previously since I am 95% sure that I used the same code. 😂

// Project level (build.gradle.kts)
// ... some code ...

apply(plugin = "org.jetbrains.dokka")

allprojects {
// ... some code ...
    val dokkaVersion: String by rootProject.extra
    val currentVersion = evaluateVersionName()
    pluginManager.withPlugin("org.jetbrains.dokka") {
        afterEvaluate {
            val dokkaPlugin by configurations
            dependencies {
                dokkaPlugin("org.jetbrains.dokka:android-documentation-plugin:$dokkaVersion")
                dokkaPlugin("org.jetbrains.dokka:versioning-plugin:$dokkaVersion")
            }
            this.tasks.withType(DokkaMultiModuleTask::class) {
                pluginConfiguration<org.jetbrains.dokka.versioning.VersioningPlugin, org.jetbrains.dokka.versioning.VersioningConfiguration> {
                    version = currentVersion
                    olderVersionsDir = file("documentation/oldVersions")
                    renderVersionsNavigationOnAllPages = true
                }
                pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
                    customAssets = listOf(file("documentation/logo-icon.svg"))
                }
                outputDirectory.set(file("documentation/html"))
                includes.from("documentation/packages.md")
            }
        }
    }
}

[andylamax]

Kudos mate, I think I too missed that

renderVersionsNavigationOnAllPages = true

Will try it out in the near future and report back here

[Ignat Beresnev]

I believe renderVersionsNavigationOnAllPages is set to true by default, so there should be no need to set it yourself

I'm glad it worked!