Hi, I have an issue with the latest dokka (`1.4.20`), which I try to migrate our `0.9.18` setup to: ...

# dokka

[marco.lied]

Hi, I have an issue with the latest dokka (1.4.20), which I try to migrate our 0.9.18 setup to:
The includes are not used like in the old dokka before. We have a README.md with the # Module <module-name> tag but the README.md seems not to be parsed and added tot the dokka outout.
No matter if I use includes.setFrom(files("README.md")) or includes.from(files("README.md"))

Can I somehow trace if the README.md is used correctly? --debug does not report any meaningful information here

[Siggi Gunnarss]

I has some gradle/groovy issue where the task configuration didn't work at all until I used:

tasks.dokkaHtml.configure {

    dokkaSourceSets {
        configureEach {
            includes.from("README.md")

the other syntaxes on the dokka documentation failed for me for some reason, i didn't dig into it

[marco.lied]

Thanks for the quick reply but for me it makes no difference.

[marco.lied]

Its considering all conflig flags except the includes as far as I can tell

[Siggi Gunnarss]

Ok, must be working then. if the files() syntax is supposed to work and the file is in the module root, I can't imagine what the problem is, it's not easy to debug gradle issues

[Kamil Doległo]

Can you send me your dokka configuration please?

[Kamil Doległo]

If you want to debug it yourself then remote debug is the best bet

[marco.lied]

tasks.dokkaHtml.configure {
    outputDirectory = new File(buildDir, "javadoc")

    dokkaSourceSets {
        named("main") {
        
            // Do not create index pages for empty packages
            skipEmptyPackages = true
            
            // Do not output deprecated members. Applies globally, can be overridden by packageOptions
            skipDeprecated = false

            // Emit warnings about not documented members. Applies globally, also can be overridden by packageOptions
            reportUndocumented = true

            // Platform used for code analysis. See the "Platforms" section of this readme
            platform.set(org.jetbrains.dokka.Platform.jvm)

            // Used for linking to JDK documentation
            jdkVersion = 8

            // Disable linking to online kotlin-stdlib documentation
            noStdlibLink = false

            // Disable linking to online JDK documentation
            noJdkLink = false

            // Disable linking to online Android documentation (only applicable for Android projects)
            noAndroidSdkLink = false

            includes.from("README.md")
            // includes.from(files(project.ext.dokkaIncludes))
        }
    }
}

[marco.lied]

nothing really special

[marco.lied]

only the README.md is normally injected through an ext prop

[Kamil Doległo]

Looks like a Groovy syntax

[Kamil Doległo]

Basically everything is discarded due to the = operator

[Kamil Doległo]

You should use set() instead of =

[Kamil Doległo]

Why does it happen? I don’t know, neither do guys from Gradle

[Kamil Doległo]

Also the platforms is no longer needed

[Kamil Doległo]

I’ll also give you the same piece of advice I always give - consider using .kts files instead of Groovy ones. You’ll get code completion and meaningful error messages. This wouldn’t even compile without set() and would be debuggable much easier. Also you can always mix .kts and non-kts files, if you don’t want to migrate the whole codebase

[marco.lied]

Thanks Kamil I’ll have a look tomorrow and will comeback to you.

Regarding the .kts switch is difficult we have about 70 single frameworks to maintain and switching the complete gradle setup is a huge effort here
I just read the possibility of splitting it, I’ll check that. Thank you!

[marco.lied]

Calling the set and everything works 🎉

[marco.lied]

but another question: Is there a possibility to get rid of the “commons” platform? Because we currently have only androidJVM code and the commons tab is just empty

[Kamil Doległo]

Strange that it renders then. Are you sure you’re using the kotlin android plugin, not the multiplatform one?
If so, could you please create a MRE for that?

[marco.lied]

We are using apply plugin: 'kotlin-android' and apply plugin: 'com.android.library' so we are building only android libraries.

And another question: Can I somehow deactivate the search bar or fix it, that it works locally? We’re not hosting the docs we are just shipping them, but the search is not working and in the Safari analyze it’s said, that this script is only allowed to run with HTTP.

[marco.lied]

I’ll try to create an MRE for you later today and create an issue on github

[Kamil Doległo]

Thanks! Search should work locally AFAIK, @Marcin Aman?

[Marcin Aman]

The searchbar uses local files so all you need is a local http server (which is also required to run other parts like navigation). The one thing we are downloading from the internet are fonts, but even if somebody doesn’t have access to the web it will fallback to local fonts.

[marco.lied]

If you ship the documentation with a binary as zip, you typically don’t have a local HTTP server running. The 0.9.18 style didn’t had this requirement.
But there is no setting to not generate the search or navigation bar? So we need to patch the CSS or generated HTML manually?

[Marcin Aman]

Right now you need to patch it manually, there is no way to omit those elements.

I think that we can do some things to improve your usecase, thats why i’ve created an issue: https://github.com/Kotlin/dokka/issues/1795

[marco.lied]

Ok thanks!

[marco.lied]

ignoring the scripts folder and setting the width of leftColumn in the sytles.css seem to fit my purpose, but it would be nicer to add an offline output format or so.