Hi there! I've added Dokka to my multiplatform + multimodule project and it works like a charm! The ...

# dokka

[addamsson]

Hi there!
I've added Dokka to my multiplatform + multimodule project and it works like a charm! The only problem I bumped into is that Dokka generates a file called -modules.html into the root directory of the resulting documentation instead of generating an index.html file. How can I tell Dokka to create an index.html instead? If I rename the file by hand it works, but I'd like to automate this.

[Big Chungus]

You can't. But you can automate renaming with custom gradle task

[addamsson]

thanks!

[Marcin Aman]

We are working on improving the multimodule experience. This file will be renamed to index.html probably in next release

[addamsson]

This sounds great! I'm releasing the docs only when a new version is deployed so this is not a serious issue.

[addamsson]

Anyway, I'm really happy that Dokka works so well now, I used to struggle with it a lot (until I gave up)

[addamsson]

@Marcin Aman a small suggestion: It is not crystal clear how @sample works. I had to look into Kotlin in Action and piece it together to figure this out. Maybe the docs can be improved a bit

[addamsson]

another thing that I bumped into is that i have to pass a function name to @sample so my sample cannot contain imports. my current workaround is that i add the imports as comments

[addamsson]

is there a better workaround for this?

[addamsson]

example:

[addamsson]

https://hexworks.github.io/zircon/2020.1.8-PREVIEW/zircon.core/zircon.core/org.hexworks.zircon.api.component/-fragment/index.html

[Marcin Aman]

Thats weird, on my small project i run a basic example:

package samples

import example.Clock

object Samples {
    fun js() {
        class SampleClock : Clock(10) {
            override fun equals(other: Any?): Boolean = true
        }
        println("Hi, JS!")
    }
}

And i get this import. Isn't it just hidden for you? (there is a plus icon on the top of the sample to expand it, they are present in the link you provided)

Also if you want a sample-specific imports you either need to create a file per sample or use your comment method.

As for the guide: it is in progress. Not only for the samples but for other dokka features as well.

[addamsson]

What is your config for this?

[addamsson]

I have this in my `build.gradle.kts`: samples.from("src/commonMain/kotlin/org/hexworks/zircon/samples")

[addamsson]

and this is my `@sample`:

@sample org.hexworks.zircon.samples.ComponentSamples.fragment

[addamsson]

object ComponentSamples {

    fun fragment() {
        // import org.hexworks.cobalt.events.api.Subscription
        // import org.hexworks.zircon.api.Components
        // import org.hexworks.zircon.api.component.Fragment
        // import org.hexworks.zircon.api.uievent.ComponentEventType

        class ConfirmButton : Fragment {

            override val root = Components.button()
                    .withText("Confirm")
                    .build()

            fun onConfirm(fn: () -> Unit): Subscription {
                return root.processComponentEvents(ComponentEventType.ACTIVATED) {
                    fn()
                }
            }
        }
    }

}

[addamsson]

the problem is that if I use @sample org.hexworks.zircon.samples.ComponentSamples all I can see in the samples block is org.hexworks.zircon.samples.ComponentSamples and no code

[addamsson]

oh, i'm stupid

[addamsson]

it was a typo on my part

[addamsson]

now i see the contents of the class properly 👍 I don't see the imports though

[Marcin Aman]

Could you click the + above the sample code and see what is present there?

[addamsson]

ah, it is there

[addamsson]

great

[addamsson]

👍

[addamsson]

i'm so happy

[addamsson]

i was struggling with Dokka so much

[addamsson]

can I somehow change this part?

[addamsson]

the docs + icon

[Marcin Aman]

you need to provide it in your build.gradle as a base plugin specific configuration with path to css and image. You can either do it by adding a base plugin to a buildscript -> dependencies -> classpath and using something like this:

pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
    customAssets = listOf(file("<path to asset>"))
    customStyleSheets = listOf(file("<path to custom stylesheet>"))
}

Adding a base plugin is required to resolve those types.

If you dont want to add this to your classpath you can just pase a json.

Relevant links:
https://kotlin.github.io/dokka/1.4.10.2/user_guide/gradle/usage/#applying-plugins
https://github.com/Kotlin/dokka/blob/master/docs/src/doc/docs/user_guide/base-specific/frontend.md

[addamsson]

i'd like to re-use the same css

[addamsson]

or should i just copy this?

[Marcin Aman]

If all you need is replacing the logo and you need to add it in assets and create a css file named logo-styles.css with this one line:

#logo {
    background-image: url('<https://upload.wikimedia.org/wikipedia/commons/9/9d/Ubuntu_logo.svg>');
    /* other styles required to make your page pretty */
}

Depending on your logo size/personal preference you can tweak it later

[addamsson]

thanks

[gaetan]

I’m sorry @Marcin Aman but I find the documentation and the instruction very unclear.

What is “`pluginConfiguration` block”?

[gaetan]

Is it in gradle API?

[gaetan]

A complete sample project with custom logo, css would help a lot.

[Marcin Aman]

Something like this works for me: https://github.com/MarcinAman/dokka-example
You can override more styles if you like by adding custom css files with the names specified here: https://kotlin.github.io/dokka/1.4.10.2/user_guide/base-specific/frontend/