With Dokka 2.1.0, how would I create a plugin supp...

# dokka

[Oliver.O]

With Dokka 2.1.0, how would I create a plugin suppressing extension functions and properties in the top-level navigation? Failed attempt in 🧵.

[Oliver.O]

This is how I started, but I couldn't make it compile:

package de.infix.testBalloon.dokka

import org.jetbrains.dokka.base.DokkaBase
import org.jetbrains.dokka.base.renderers.html.NavigationNode
import org.jetbrains.dokka.base.renderers.html.NavigationPageInstaller
import org.jetbrains.dokka.pages.RootPageNode
import org.jetbrains.dokka.plugability.DokkaContext
import org.jetbrains.dokka.plugability.DokkaPlugin
import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement

@Suppress("unused")
class DokkaHideExtensionsOnTopLevel : DokkaPlugin() {
    val myFilterExtension by extending {
        plugin<DokkaBase>().navigationPageInstaller providing ::DokkaHideExtensionsOnTopLevelTransformer
    }

    @DokkaPluginApiPreview
    override fun pluginApiPreviewAcknowledgement() = PluginApiPreviewAcknowledgement
}

private class DokkaHideExtensionsOnTopLevelTransformer(context: DokkaContext) : NavigationPageInstaller(context) {

    override fun navigableChildren(input: RootPageNode): NavigationNode = super.navigableChildren(input)
}

[Oliver.O]

The entire extension mechanism is still a mystery to me, which I could not decipher by studying the docs.

[Oleg Yukhnevich]

The entire extension mechanism is still a mystery to me

true 😞

In your case, you need to extend not navigationPageInstaller but htmlPreprocessors, as navigationPageInstaller is just one of many. So it will look like this:

class DokkaHideExtensionsOnTopLevel : DokkaPlugin() {
    val dokkaBase = plugin<DokkaBase>()
    val myFilterExtension: Extension<PageTransformer, *, *> by extending {
        dokkaBase.htmlPreprocessors providing ::DokkaHideExtensionsOnTopLevelTransformer override dokkaBase.navigationPageInstaller
    }

    @DokkaPluginApiPreview
    override fun pluginApiPreviewAcknowledgement() = PluginApiPreviewAcknowledgement
}

Here, you extend dokkaBase.htmlPreprocessors by providing a new processor DokkaHideExtensionsOnTopLevelTransformer, which overrides dokkaBase.navigationPageInstaller

[Oleg Yukhnevich]

Overall, you are probably on the right path, though I haven't seen anyone done anything like this
Do you mind sharing a reason for this?

[Oliver.O]

Thanks for the quick feedback! I'll try the above and report back on how it went.

Why would I like to hide extension functions in the top-level navigation? TestBalloon tries to be powerful yet really easy to use. A small API surface contributes to that goal, getting users oriented quickly with a low cognitive load. Ideally, the navigation would reflect that.

Basically, TestBalloon has just these two functions, testSuite and test. And it has a TestConfig builder with a number of extension functions to customize its behavior. The idea is to hide the TestConfig extensions from the navigation, then let them explore them under the TestConfig class. I'm not sure whether that's the best solution, but it's one I would like to explore.

[Oliver.O]

That's what it looks like currently:

[Oleg Yukhnevich]

Thanks! I do agree that if the project (library) has a lot of extension functions, the navigation might look a bit strange, as it will contain just function names, without real context on how to use them.
Though it really depends on the project, and there is no "one size fits all" here.
Could you also create an issue, as you see it, so that it will be recorded somewhere? I haven't found similar issues through a quick search. I could create it by myself, but I could miss some details 😞

[Oliver.O]

I'll create an issue. Just let me explore a bit more before doing so. I'm making a note in my TODO list so I don't forget.