https://kotlinlang.org logo
Title
a

andylamax

04/16/2023, 12:28 AM
How does one publish documentation of the current and old versions of the same project??
s

simon.vergauwen

04/16/2023, 6:30 AM
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
a

andylamax

04/16/2023, 9:50 AM
s

simon.vergauwen

04/16/2023, 10:00 AM
Oh, very interesting! Thank you for sharing, will look into this.
a

andylamax

04/16/2023, 11:20 AM
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
h

hfhbd

04/17/2023, 5:08 AM
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).
a

andylamax

04/17/2023, 9:44 AM
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
i

Ignat Beresnev

04/17/2023, 12:23 PM
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 🙂
a

Adrian Landborn

04/17/2023, 2:25 PM
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. 🤔
a

andylamax

04/17/2023, 2:26 PM
What you are saying @Adrian Landborn is exactly what I ended up achieving. So, I assumed I did not understand the documentation well
a

Adrian Landborn

04/17/2023, 2:31 PM
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")
        }
    }
}
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)
        }
    }
}
i

Ignat Beresnev

04/17/2023, 3:40 PM
@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")
}
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.
a

Adrian Landborn

04/17/2023, 4:20 PM
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)
i

Ignat Beresnev

04/17/2023, 4:29 PM
It has to be
dokkaHtmlPlugin(..)
or
dokkaPlugin(..)
specifically, I believe. Not
classpath(..)
a

Adrian Landborn

04/17/2023, 4:31 PM
As mentioned everything else is working apart from the versioning plugin
i

Ignat Beresnev

04/17/2023, 4:32 PM
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.
a

Adrian Landborn

04/17/2023, 4:34 PM
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)
        }
    }
}
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?
        }
    }
}
i

Ignat Beresnev

04/17/2023, 4:37 PM
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)
    }
}
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
a

Adrian Landborn

04/17/2023, 4:59 PM
Thanks for the help @Ignat Beresnev. It’s getting late here in Sweden. Will continue looking at it tomorrow.
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…
i

Ignat Beresnev

04/17/2023, 5:11 PM
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
a

Adrian Landborn

04/17/2023, 5:11 PM
Oh, were using
allprojects
and not
subprojects
I guess we can use is similary
I’ve cloned and tried out the Example projects but some things does not add up when running with an Android project. 🤔
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")
            }
        }
    }
}
a

andylamax

04/21/2023, 2:40 PM
Kudos mate, I think I too missed that
renderVersionsNavigationOnAllPages = true
Will try it out in the near future and report back here
i

Ignat Beresnev

04/26/2023, 2:02 PM
I believe
renderVersionsNavigationOnAllPages
is set to
true
by default, so there should be no need to set it yourself I'm glad it worked!