adamko-dev / dokkatoo Goto Github PK

The following snippet introduces references to objects that cause incompatibilities with Gradle's configuration caching:

tasks {
    dokkatooGenerateModuleHtml.configure {
        dokkaSourceSets.configureEach {
            sourceLink {
                // ...
            }
        }
    }
}

Writing the configuration cache fails (see also):

⌄ task:dokkatooGenerateModuleHtml of type dev.adamko.dokkatoo.tasks.DokkatooGenerateTask
  ⌄ field__dokkaSourceSets__ of dev.adamko.dokkatoo.tasks.DokkatooGenerateTask
    ⌄ bean of type org.gradle.api.internal.FactoryNamedDomainObjectContainer
      ⌄ fieldeventRegister of org.gradle.api.internal.FactoryNamedDomainObjectContainer
        ⌄ bean of type org.gradle.api.internal.collections.DefaultCollectionEventRegister
          ⌄ fieldaddActions of org.gradle.api.internal.collections.DefaultCollectionEventRegister
            ⌄ bean of type org.gradle.internal.ImmutableActionSet$SetWithFewActions
              ⌄ fieldactions of org.gradle.internal.ImmutableActionSet$SetWithFewActions
                ⌄ bean of type org.gradle.api.internal.DefaultMutationGuard$1
                  ⌄ fieldval$action of org.gradle.api.internal.DefaultMutationGuard$1
                    ⌄ bean of type org.gradle.api.internal.DefaultMutationGuard$1
                      ⌄ fieldval$action of org.gradle.api.internal.DefaultMutationGuard$1
                        ⌄ bean of type org.gradle.api.internal.DefaultCollectionCallbackActionDecorator$BuildOperationEmittingAction
                          ⌄ fielddelegate of org.gradle.api.internal.DefaultCollectionCallbackActionDecorator$BuildOperationEmittingAction
                            ⌄ bean of type org.gradle.configuration.internal.DefaultUserCodeApplicationContext$CurrentApplication$1
                              ⌄ fieldval$action of org.gradle.configuration.internal.DefaultUserCodeApplicationContext$CurrentApplication$1
                                ⌄ bean of type Build_gradle$4$5$1
                                  ⌄ fieldthis$0 of Build_gradle$4$5$1
                                    ■⚠️cannot serialize Gradle script object references as these are not supported with the configuration cache.[ ?](https://docs.gradle.org/8.1/userguide/configuration_cache.html#config_cache:requirements:disallowed_types)

This issue does not occur when configuring the sourceLink via the dokkatoo extension.

It appears that the javadoc.jar file served at the Gradle Plugin Portal is empty when extracted - is this intentional?

Some problems were found with the configuration of task ':project:prepareDokkatooParametersJavadoc' (type 'DokkatooPrepareParametersTask').
  - Gradle detected a problem with the following location: '/project/.gradle/kotlin/kotlinTransformedCInteropMetadataLibraries/org.jetbrains.kotlinx-atomicfu-0.20.2-nativeMain-cinterop/org.jetbrains.kotlinx_atomicfu-cinterop-interop-nfvfsw.klib'.
    
    Reason: Task ':apiresult:prepareDokkatooParametersJavadoc' uses this output of task ':project2:transformIosMainCInteropDependenciesMetadataForIde' without declaring an explicit or implicit dependency. This can lead to incorrect results being produced, depending on what order the tasks are executed.
    
    Possible solutions:
      1. Declare task ':project2:transformIosMainCInteropDependenciesMetadataForIde' as an input of ':project:prepareDokkatooParametersJavadoc'.
      2. Declare an explicit dependency on ':project2:transformIosMainCInteropDependenciesMetadataForIde' from ':project:prepareDokkatooParametersJavadoc' using Task#dependsOn.
      3. Declare an explicit dependency on ':project2:transformIosMainCInteropDependenciesMetadataForIde' from ':project:prepareDokkatooParametersJavadoc' using Task#mustRunAfter.
    
    Please refer to https://docs.gradle.org/8.1.1/userguide/validation_problems.html#implicit_dependency for more details about this problem.

gradle.properties includes:

kotlin.mpp.enableCInteropCommonization=true
kotlin.mpp.stability.nowarn=true
org.gradle.unsafe.configuration-cache=true

Currently when a HTML Publication has multiple modules but the all-modules-page-plugin is missing, then Dokka will happily run and report no errors.

This is incredibly frustrating to fix! It's really baffling how everything looks like it's set up correctly, but the generated Publication is empty.

It should be quite simple to create a check to verify that if a Publication has multiple modules then all-modules-page-plugin should be present, otherwise, log an informative message.

Related

• #156

Dokka 1.9.0 was just released - I presume the Dokka version can be updated as per #88 but there might be breaking changes :P

Reason for the request: gradle/gradle#26479

Currently in order to create a Dokka publication that aggregates subprojects, it's required to manually add a dependency on all-modules-page-plugin

plugins {
  kotlin("jvm") version "1.7.20" apply false
  id("dev.adamko.dokkatoo") version "0.0.2-SNAPSHOT"
}

dependencies {
  dokkatoo(project(":parentProject:childProjectA"))
  dokkatoo(project(":parentProject:childProjectB"))

  // A dependency on all-modules-page-plugin is required for aggregating subprojects.
  // A version is not required, Dokkatoo will automatically add one.
  dokkatooPluginHtml("org.jetbrains.dokka:all-modules-page-plugin")
}

This dependency should be added automatically.

Gradle 8.6, Dokkatoo 2.1.0

> Task :buildSrc:compileKotlin
w: file:///home/me/prj/buildSrc/build/generated-sources/kotlin-dsl-accessors/kotlin/gradle/kotlin/dsl/accessors/_449187fc874922a2ad1c7ba7612ed738/Accessorsd6bujp36mck8x4gylrvrl8096.kt:65:103 Internal Dokkatoo API - may change at any time without notice
w: file:///home/me/prj/buildSrc/build/generated-sources/kotlin-dsl-accessors/kotlin/gradle/kotlin/dsl/accessors/_449187fc874922a2ad1c7ba7612ed738/Accessorsd6bujp36mck8x4gylrvrl8096.kt:66:152 Internal Dokkatoo API - may change at any time without notice
w: file:///home/me/prj/buildSrc/build/generated-sources/kotlin-dsl-accessors/kotlin/gradle/kotlin/dsl/accessors/_449187fc874922a2ad1c7ba7612ed738/Accessorsd6bujp36mck8x4gylrvrl8096.kt:72:120 Internal Dokkatoo API - may change at any time without notice
w: file:///home/me/prj/buildSrc/build/generated-sources/kotlin-dsl-accessors/kotlin/gradle/kotlin/dsl/accessors/_449187fc874922a2ad1c7ba7612ed738/Accessorsd6bujp36mck8x4gylrvrl8096.kt:73:64 Internal Dokkatoo API - may change at any time without notice
w: file:///home/me/prj/buildSrc/build/generated-sources/kotlin-dsl-accessors/kotlin/gradle/kotlin/dsl/accessors/_449187fc874922a2ad1c7ba7612ed738/Accessorsd6bujp36mck8x4gylrvrl8096.kt:73:116 Internal Dokkatoo API - may change at any time without notice

We are using Dokkatoo at Gradle to generate Kotlin DSL reference docs, see here:

• gradle/gradle#24302

Everything was fine on version 0.0.4 of the plugin, but now, after upgrading to 1.0.0, I can't get the custom stylesheets and assets to work. I think I'm using them as advertised in the documentation, see here.

In general, any feedback on our attempts is welcome.

A warning is logged during AndroidProjectIntegrationTest

Configuration 'dokkatooHtmlResolver' was resolved during configuration time.
This is a build performance and scalability issue.
See https://github.com/gradle/gradle/issues/2298
Run with --info for a stacktrace.

As explained in gradle/gradle#2298 it's probably Gradle being overly sensitive and can be ignored, but it would be nice to be completely compliant.

The warning is probably caused by #128. Perhaps there's a better way to do it, especially after the changes in #155.

Current behavior:

externalDocumentationLinks {
  register("serialization") {
    url("https://kotlin.github.io/kotlinx.serialization")
  }
}

New design:

externalDocumentationLinks {
  register("https://kotlin.github.io/kotlinx.serialization")
}

I guess you don't use the name at all?

Thanks a lot for checking! It's a good sign.

I'm not sure what the problem might be with the index.html file. Possibly it's a bug from another change I've made since v1.3.0.

I'll finish up the work in this PR and if there's another bug to fix, then we can make a new issue for it.

Originally posted by @aSemy in #76 (comment)

As requested, here's the issue regarding above with a build scan of the error

I've tried checking which commit specifically introduces this change but to no avail... 😕

This error message is somehow misleading, because it does not contain any url or the name of the registered Link domain-object.

Failed to download package-list from https://package-list, this might suggest that remote resource is not available, module is empty or dokka output got corrupted

I used Dokkatoo 1.3.0 and Gradle 8.1.1.
I will create a reproducer later, but this is only possible by removing each url entry and trial and error.

It appears that sub-modules don't inherit the footer message defined from the root module's pluginConfiguration.html block:

plugins {
  dev.adamko.`dokkatoo-html`
}

dokkatoo {
    pluginsConfiguration.html {
        // ...
        footerMessage.set("&copy; 2023 <...>")
    }
}

• Root docs page
• Sub-module docs page

Dokka has a new release, 1.8.20.

The version of Dokka can be updated in libs.versions.toml

This will have some impact on the example and integration-test projects. The Dokkatoo projects should be updated to mirror any changes in their Dokka sibling.

If you're reading this because you use Dokkatoo and you want to use Dokka 1.8.20, then you don't need to wait for Dokkatoo: go ahead and set the version of Dokka that Dokkatoo will use:

// build.gradle.kts

plugins {
  id("dev.adamko.dokkatoo-html")
}

dokkatoo {
  versions {
    jetbrainsDokka.set("1.8.20")
  }
}

(Note that you should do this in all subprojects that has Dokkatoo applied, which should be easy because you're configuring Dokkatoo using a convention plugin... right?)

A contributing guide for this repository would be ideal for first-time contributors (e.g. how to set up the project for local development, adding new features, navigating around the codebase, commit guidelines, etc), and also standardises project conventions/rules (if any) for existing contributors.

The BasicProjectIntegrationTest is failing on Windows, but passing on macOS and Unix. It's very weird.

2023-02-18T14:13:06.9914069Z  FAILURE: Build failed with an exception.
2023-02-18T14:13:06.9914629Z  
2023-02-18T14:13:06.9914944Z  * Where:
2023-02-18T14:13:06.9916109Z  Build file 'D:\a\bug-gradle-testkit\bug-gradle-testkit\modules\integration-tests\build\test-temp-dir\it\it-basic\dokka\build.gradle.kts' line: 8
2023-02-18T14:13:06.9916676Z  
2023-02-18T14:13:06.9917234Z  * What went wrong:
2023-02-18T14:13:06.9919137Z  Plugin [id: 'org.jetbrains.kotlin.jvm', version: '1.7.22'] was not found in any of the following sources:
2023-02-18T14:13:06.9919710Z  
2023-02-18T14:13:06.9920335Z  - Gradle Core Plugins (plugin is not in 'org.gradle' namespace)
2023-02-18T14:13:06.9921467Z  - Plugin Repositories (could not resolve plugin artifact 'org.jetbrains.kotlin.jvm:org.jetbrains.kotlin.jvm.gradle.plugin:1.7.22')
2023-02-18T14:13:06.9923394Z    Searched in the following repositories:     MavenLocal(file:/C:/Users/runneradmin/.m2/repository)     maven(https://cache-redirector.jetbrains.com/jcenter.bintray.com)     MavenRepo     Gradle Central Plugin Repository     Google     maven2(https://cache-redirector.jetbrains.com/dl.bintray.com/kotlin/kotlin-eap)     maven3(https://cache-redirector.jetbrains.com/dl.bintray.com/kotlin/kotlin-dev)
2023-02-18T14:13:06.9924693Z  

I've created an issue for Gradle gradle/gradle#23959

• Re-enable the Windows tests requirement for GitHub merging

Currently, the examples expect a testMavenRepo property to be defined, which is automatically generated by the updateDokkatooExamplesGradleProperties task in a gradle.properties file. However, this file doesn't appear to be generated when adding the examples as includedBuilds and running the Tests workflow - see this build step's logs:

Error resolving plugin [id: 'org.jetbrains.kotlin.jvm', version: '1.8.10']
> Cannot query the value of this provider because it has no value available.

Additionally, some examples might want to add custom properties of their own, or the plugins/code used (for e.g. Kotlin Multiplatform) expects a property (in this case, kotlin.mpp.androidSourceSetLayoutVersion=2/kotlin.mpp.androidSourceSetLayoutVersion1.nowarn=true to be set) to use a specific feature.

I'm not sure as to a better approach of doing this - maybe it could be defined as a custom property in a custom .properties file, which can then be loaded in via java.util.Properties, or maybe as an environment variable?

The current design requires to add all projects manually in the dependency block of the root project:

dependencies {
  dokkatoo(projects.foo)
}

Adding some default mechanism would be nice to not add all projects manually. This is somehow annoying with projects containing many projects.

One option:
Use a build service to register a project when the dokkatoo plugin is applied.
The root project should create the build service (it is evaluated at first) and could depend on the registered projects using dependencies.addLater.

Originally posted by @hfhbd in #14 (comment)

I have applied Dokkatoo in a multi-module project, and have successfully aggregated and generated a HTML site.

After generating the site I made changes to a src/main/kotlin file in a subproject, and re-ran Dokkatoo.

I expected that the site would be updated to reflect my new changes, however Dokkatoo did not re-run and said it was up-to-date.

How to fix?

A fix requires some thought. How can Gradle recognise that a Dokka Module is outdated? Create a md5 hash of the source set files and include in module_descriptor.json?

Tasks

• Determine fix
• Apply fix
• Create a test. MultiModuleFunctionalTest is a good basis for it.

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Awaiting Schedule

These updates are awaiting their schedule. Click on a checkbox to get an update now.

• Update dependency @types/react-dom to v18.2.25
• Update dependency typescript to v5.4.5
• Update kotlin monorepo (org.jetbrains.kotlin:kotlin-klib-commonizer-api, org.jetbrains.kotlin:kotlin-gradle-plugin, org.jetbrains.kotlin:kotlin-test)
• Update dependency org.jetbrains.kotlin:kotlin-test to v2

Edited/Blocked

These updates have been manually edited so Renovate will no longer make changes. To discard all commits and start over, click on a checkbox.

• Update dependency gradle to v8.7

Pending Status Checks

These updates await pending status checks. To force their creation now, click the checkbox below.

• Update dependency io.ktor:ktor-bom to v2.3.10
• Update gradlePlugin.android to v8.3.2 (com.android.tools.build:gradle-api, com.android.tools.build:gradle)
• Update dependency com.microsoft.playwright:playwright to v1.43.0

Detected dependencies

• Check this box to trigger a request for Renovate to run again on this repository

Hi!

I have a project in which I applied the Dokkatoo plugin. I'm currently refactoring it to use convention plugins, and in the process something strange broke. I don't know how to debug it.

The project is structured as follows:

playground/
    app/build.gradle.kts
    core/build.gradle.kts
    build.gradle.kts

The :core project has Dokkatoo. The :app project doesn't. The root project has a dependency on :core.

Previously, I ran ./gradlew :dokkatooGeneratePublicationHtml to generate the HTML output. However, now, it only generates an empty build/dokka/core directory.

If I run ./gradlew dokkatooGenerate, I get the following link printed in the terminal: http://localhost:63342/playground/build/dokka/html/index.html. Opening that link in the browser does allow me to browse the generated documentation. However, that file doesn't exist. The build/dokka directory only contains a subdirectory called core, there are no other files.

What could be the cause? I don't understand how this can happen.

Reproduction:

• Repository https://gitlab.com/opensavvy/playgrounds/gradle
• Commit 6d3edba36598d9d4d1fc1e5906bf6be1f6b698d3

Other useful links:

• Code of the opensavvyConventions.plugins.base convention plugin: here (unrelated to Dokka)
• Code of the opensavvyConventions.plugins.root convention plugin: here (applies the plugin + the dependencies workaround)
• Code of the opensavvyConventions.plugins.kotlin.library convention plugin: here (applies the plugin + configures the project name + includes the README, etc)

Follow on from #50 (comment).

Repro: cashapp/redwood#936

Things tried:

• Checked dokka_parameters.json and I can't see any reference to local project dependency JARs.
• Moving to plugins instead of apply plugin. Same result.
• Workaround from #44. Unfortunately that results in Could not create domain object 'commonMain' (DokkaSourceSetSpec)

I tried to run dokkatoo example but I failed as below. I though it's difficult because dokkatoo doesn't provide readme about how to run example.

➜  dokkatoo git:(main) pwd
/Users/sungho.moon/gopath/src/github.com/adamko-dev/dokkatoo/examples/multimodule-example/dokkatoo
➜  dokkatoo git:(main) ../../../gradlew clean dokkatooGenerate
> Task :buildSrc:generateExternalPluginSpecBuilders FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':buildSrc:generateExternalPluginSpecBuilders'.
> Could not resolve all files for configuration ':buildSrc:compileClasspath'.
   > Could not find dev.adamko.dokkatoo:dokkatoo-plugin:2.1.0-SNAPSHOT.
     Searched in the following locations:
       - https://repo.maven.apache.org/maven2/dev/adamko/dokkatoo/dokkatoo-plugin/2.1.0-SNAPSHOT/maven-metadata.xml
       - https://repo.maven.apache.org/maven2/dev/adamko/dokkatoo/dokkatoo-plugin/2.1.0-SNAPSHOT/dokkatoo-plugin-2.1.0-SNAPSHOT.pom
       - https://plugins.gradle.org/m2/dev/adamko/dokkatoo/dokkatoo-plugin/2.1.0-SNAPSHOT/maven-metadata.xml
       - https://plugins.gradle.org/m2/dev/adamko/dokkatoo/dokkatoo-plugin/2.1.0-SNAPSHOT/dokkatoo-plugin-2.1.0-SNAPSHOT.pom
       - file:/Users/sungho.moon/gopath/src/github.com/adamko-dev/dokkatoo/build/test-maven-repo/dev/adamko/dokkatoo/dokkatoo-plugin/2.1.0-SNAPSHOT/maven-metadata.xml
       - file:/Users/sungho.moon/gopath/src/github.com/adamko-dev/dokkatoo/build/test-maven-repo/dev/adamko/dokkatoo/dokkatoo-plugin/2.1.0-SNAPSHOT/dokkatoo-plugin-2.1.0-SNAPSHOT.pom
     Required by:
         project :buildSrc

* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.

BUILD FAILED in 4s
1 actionable task: 1 executed

Currently DokkatooKotlinAdapter causes errors with the Gradle Configuration Cache.

I tried to refactor the current Dokka GP code, which is spread out across a few files

• https://github.com/Kotlin/dokka/tree/1e10c6f47d605e1e730cb58aa44f3051ec5a493b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin
• https://github.com/Kotlin/dokka/blob/1e10c6f47d605e1e730cb58aa44f3051ec5a493b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/sourceSetKotlinGistConfiguration.kt

But apparently I made it worse!

There are some Configuration Cache tests that I've disabled for now, but are ready to enable.

It would be nice to see an example that uses Gradle's composite builds feature.

e.g. settings.gradle.kts:

pluginManagement {
  // ...
  includeBuild("plugins/example")
}

root build.gradle.kts:

plugins {
  alias(libs.plugins.dokkatoo.html)
}

dependencies {
  dokkatoo(/* how would the "example" plugin be included? */)
}

plugins/example/build.gradle.kts:

plugins {
  alias(libs.plugins.dokkatoo.html)
}

// ...

Attempting something like dokkatoo(gradle.includeBuild("plugins/example")) doesn't work as the dokkatoo config doesn't seem to support IncludedBuilds

Seems that Kotlin Multiplatform builds result in an issue similar to #44:

plugins {
    kotlin("multiplatform") // Using Kotlin 1.8.20
    dev.adamko.`dokkatoo-html` // Using v1.1.1
}

kotlin {
    jvm {
        compilations.all {
            compilerOptions.configure {
                jvmTarget = JvmTarget.JVM_1_8
            }
        }
        withJava()
        testRuns["test"].executionTask.configure {
            useJUnitPlatform()
        }
    }
    js(IR) {
        browser {
            commonWebpackConfig {
                cssSupport {
                    enabled = true
                }
            }
        }
    }

    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation(libs.ktor.client.core)
                implementation(libs.kotlinx.serialization.json)
            }
        }
        val commonTest by getting {
            dependencies {
                implementation(kotlin("test"))
            }
        }
        val jvmMain by getting
        val jvmTest by getting
        val jsMain by getting
        val jsTest by getting

        val samples by creating {
            dependsOn(commonMain)
        }
    }
}

dokkatoo {
    dokkatooSourceSets.configureEach {
        if (name.endsWith("Test") || name == "samples") suppress = true // Hide test/samples sources

        includes.from("Module.md")

        samples.from("src/samples/kotlin")

        // Link to source
        sourceLink {
            localDirectory = file("src/${name}/kotlin")
            remoteUrl =
                URL("https://github.com/EdricChan03/<repo>/tree/main/${project.name}/src/${name}/kotlin")
        }

        externalDocumentationLinks {
            // KotlinX docs
            val `kotlinx-coroutines` by creating {
                url("https://kotlinlang.org/api/kotlinx.coroutines/")
            }
            val `kotlinx-serialization` by creating {
                url("https://kotlinlang.org/api/kotlinx.serialization/")
            }

            // Ktor API docs
            val ktor by creating {
                url("https://api.ktor.io/ktor-client/")
                packageListUrl("https://api.ktor.io/package-list")
            }
        }
    }
}

Let me know if additional information/a reproducer is required

Previously I added NDOCs as extensions in task, believing that Gradle would generate Kotlin DSL accessors for them. This is not the case - Gradle will only generate accessors for specific types, and tasks are not one of those types.

To simplify the code, this properties should be removed and converted to abstract properties.

Example:

Should be replaced with

  @get:Nested
  abstract val generator: DokkaGeneratorParametersSpec = objects.newInstance(pluginsConfiguration)

After upgrating to 2.1.0, we started having KSP errors because the KSP classpath would select the dokkatooHtmlPublicationPluginClasspathApiOnlyConsumable variant of some projects instead of the jvmRuntimeElements ones. They are indeed quite similar:

--------------------------------------------------
Variant dokkatooHtmlPublicationPluginClasspathApiOnlyConsumable
--------------------------------------------------
Shared Dokka Plugins for consumers that will assemble a html Publication using the Dokka Module that this project produces

Capabilities
    - com.apollographql.apollo3:apollo-ast:4.0.0-beta.5-SNAPSHOT (default capability)
Attributes
    - dev.adamko.dokkatoo.classpath  = dokka-publication-plugins
    - dev.adamko.dokkatoo.format     = html
    - org.gradle.category            = library
    - org.gradle.dependency.bundling = external
    - org.gradle.jvm.environment     = standard-jvm
    - org.gradle.libraryelements     = jar
    - org.gradle.usage               = java-runtime

vs

--------------------------------------------------
Variant jvmRuntimeElements
--------------------------------------------------
Elements of runtime for main.

Capabilities
    - com.apollographql.apollo3:apollo-ast:4.0.0-beta.5-SNAPSHOT (default capability)
Attributes
    - org.gradle.category                = library
    - org.gradle.jvm.environment         = standard-jvm
    - org.gradle.libraryelements         = jar
    - org.gradle.usage                   = java-runtime
    - org.jetbrains.kotlin.platform.type = jvm
Artifacts
    - build/libs/apollo-ast-jvm-4.0.0-beta.5-SNAPSHOT.jar (artifactType = jar)

I was able to workaround by forcing "unselection" of the dokkatoo variant:

  configurations.configureEach {
    if (name.lowercase().contains("dokkatooHtmlPublicationPluginClasspathApiOnlyConsumable".lowercase())) {
      attributes {
        attribute(Usage.USAGE_ATTRIBUTE, objects.named(Usage::class.java, "poison"))
      }
    }
  }

TBH I'm not 100% what the root cause is but would it be possible to use more specific attributes for dokkatooHtmlPublicationPluginClasspathApiOnlyConsumable? Maybe org.gradle.usage = dokkatoo-plugin?

Seems that the test sources are included by default - not sure if Dokka hid it by default, but it would be nice to have an option of excluding test sources from the resulting Dokka output.

Currently, a workaround would be to remove *Test sources by setting suppress to true

Would you consider publishing the plugin to Maven Central? Gradle Plugin Portal works too but having it in Maven Central would make it more discoverable when used in convention plugins, etc... ?

Seems that the sub-project dependencies that a Gradle project has are missing from the classpath, resulting in missing information in the generated HTML docs:

The original source extends an abstract class (FromEnumValue) that comes from another project:

public companion object : EnumFromValue<Int, ActivityHeightResizeBehavior>(Default) {

This was previously present in the resulting generated docs when it was previously part of the same module, but now appears to be absent.

Here's my build config:

Root build.gradle.kts

plugins {
  dev.adamko.`dokkatoo-html`
}

dependencies {
  dokkatoo(projects.androidx.browser.browserKtx)
  dokkatoo(projects.androidx.common.commonEnums) // This is where `EnumFromValue` is defined
}

browser-ktx build.gradle.kts:

dependencies {
  api(projects.androidx.common.commonEnums)
  // ...
}

I've tried taking a look at the generated Dokka config JSON file for browser-ktx (androidx/browser/browser-ktx/build/tmp/dokkatooGenerateModuleHtml/dokka-configuration.json) and noticed that there's no presence of a common-enums module:

{
  "moduleName": "browser-ktx",
  "moduleVersion": "0.0.1-SNAPSHOT",
  "outputDir": "/{...}/androidx-ktx-extras/androidx/browser/browser-ktx/build/dokka-module/html",
  "cacheRoot": null,
  "offlineMode": false,
  "sourceSets": [
    {
      "displayName": "androidJvm",
      "sourceSetID": {
        "scopeId": ":androidx:browser:browser-ktx",
        "sourceSetName": "main"
      },
      "classpath": [
        "/{...}/.gradle/caches/modules-2/files-2.1/androidx.browser/browser/1.5.0/{...}/browser-1.5.0.aar",
        "/{...}/.gradle/caches/modules-2/files-2.1/androidx.core/core/1.1.0/{...}/core-1.1.0.aar",
        "/{...}/.gradle/caches/modules-2/files-2.1/androidx.versionedparcelable/versionedparcelable/1.1.0/{...}/versionedparcelable-1.1.0.aar",
        "/{...}/.gradle/caches/modules-2/files-2.1/androidx.collection/collection/1.1.0/{...}/collection-1.1.0.jar",
        "/{...}/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib-jdk8/1.8.21/{...}/kotlin-stdlib-jdk8-1.8.21.jar",
        "/{...}/.gradle/caches/modules-2/files-2.1/androidx.annotation/annotation-jvm/1.6.0/{...}/annotation-jvm-1.6.0.jar",
        "/{...}/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib-jdk7/1.8.21/{...}/kotlin-stdlib-jdk7-1.8.21.jar",
        "/{...}/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib/1.8.21/{...}/kotlin-stdlib-1.8.21.jar",
        "/{...}/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib-common/1.8.21/{...}/kotlin-stdlib-common-1.8.21.jar",
        "/{...}/.gradle/caches/modules-2/files-2.1/org.jetbrains/annotations/13.0/{...}/annotations-13.0.jar",
        "/{...}/.gradle/caches/modules-2/files-2.1/com.google.guava/listenablefuture/1.0/{...}/listenablefuture-1.0.jar",
        "/{...}/.gradle/caches/modules-2/files-2.1/androidx.lifecycle/lifecycle-runtime/2.0.0/{...}/lifecycle-runtime-2.0.0.aar",
        "/{...}/.gradle/caches/modules-2/files-2.1/androidx.lifecycle/lifecycle-common/2.0.0/{...}/lifecycle-common-2.0.0.jar",
        "/{...}/.gradle/caches/modules-2/files-2.1/androidx.arch.core/core-common/2.0.0/{...]/core-common-2.0.0.jar",
        "/{...}/.gradle/caches/modules-2/files-2.1/androidx.concurrent/concurrent-futures/1.0.0/{...}/concurrent-futures-1.0.0.jar",
        "/{...}/.gradle/caches/modules-2/files-2.1/androidx.interpolator/interpolator/1.0.0/{...}/interpolator-1.0.0.aar",
        "/{...}/Android/sdk/platforms/android-33/android.jar",
        "/{...}/.gradle/caches/transforms-3/{...}/transformed/browser-1.5.0/jars/classes.jar",
        "/{...}/.gradle/caches/transforms-3/{...}/transformed/core-1.1.0/jars/classes.jar",
        "/{...}/.gradle/caches/transforms-3/{...}/transformed/versionedparcelable-1.1.0/jars/classes.jar",
        "/{...}/.gradle/caches/transforms-3/{...}/transformed/lifecycle-runtime-2.0.0/jars/classes.jar",
        "/{...}/.gradle/caches/transforms-3/{...}/transformed/interpolator-1.0.0/jars/classes.jar"
      ],
      "sourceRoots": [
        "/{...}/androidx-ktx-extras/androidx/browser/browser-ktx/src/main/kotlin"
      ],
      "dependentSourceSets": [
      ],
      "samples": [
      ],
      "includes": [
        "/{...}/androidx-ktx-extras/androidx/browser/browser-ktx/Module.md"
      ],
      "includeNonPublic": false,
      "reportUndocumented": true,
      "skipEmptyPackages": true,
      "skipDeprecated": false,
      "jdkVersion": 11,
      "sourceLinks": [
        {
          "localDirectory": "/{...}/androidx-ktx-extras/androidx/browser/browser-ktx/src/main/kotlin",
          "remoteUrl": "https://github.com/EdricChan03/androidx-ktx-extras/tree/main/androidx/browser/browser-ktx/src/main/kotlin",
          "remoteLineSuffix": "#L"
        }
      ],
      "perPackageOptions": [
      ],
      "externalDocumentationLinks": [
        {
          "url": "https://developer.android.com/reference/kotlin/",
          "packageListUrl": "https://developer.android.com/reference/kotlin/package-list"
        },
        {
          "url": "https://developer.android.com/reference/kotlin/",
          "packageListUrl": "https://developer.android.com/reference/kotlin/androidx/package-list"
        },
        {
          "url": "https://docs.oracle.com/en/java/javase/11/docs/api/",
          "packageListUrl": "https://docs.oracle.com/en/java/javase/11/docs/api/element-list"
        },
        {
          "url": "https://kotlinlang.org/api/latest/jvm/stdlib/",
          "packageListUrl": "https://kotlinlang.org/api/latest/jvm/stdlib/package-list"
        }
      ],
      "languageVersion": null,
      "apiVersion": null,
      "noStdlibLink": false,
      "noJdkLink": false,
      "suppressedFiles": [
      ],
      "analysisPlatform": "jvm",
      "documentedVisibilities": [
        "PUBLIC"
      ]
    }
  ],
  "pluginsClasspath": [
    "/{...}/.gradle/caches/modules-2/files-2.1/org.jetbrains.dokka/dokka-analysis/1.8.20/{...}/dokka-analysis-1.8.20.jar",
    "/{...}/.gradle/caches/modules-2/files-2.1/org.jetbrains.dokka/templating-plugin/1.8.20/{...}/templating-plugin-1.8.20.jar",
    "/{...}/.gradle/caches/modules-2/files-2.1/org.jetbrains.dokka/dokka-base/1.8.20/{...}/dokka-base-1.8.20.jar",
    "/{...}/.gradle/caches/modules-2/files-2.1/org.jetbrains.dokka/kotlin-analysis-intellij/1.8.20/{...}/kotlin-analysis-intellij-1.8.20.jar",
    "/{...}/.gradle/caches/modules-2/files-2.1/org.jetbrains.dokka/kotlin-analysis-compiler/1.8.20/{...}/kotlin-analysis-compiler-1.8.20.jar",
    "/{...}/.gradle/caches/modules-2/files-2.1/org.freemarker/freemarker/2.3.31/{...}/freemarker-2.3.31.jar",
    "/{...}/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlinx/kotlinx-html-jvm/0.8.0/{...}/kotlinx-html-jvm-0.8.0.jar"
  ],
  "pluginsConfiguration": [
    {
      "fqPluginName": "org.jetbrains.dokka.base.DokkaBase",
      "serializationFormat": "JSON",
      "values": "{\"customAssets\":[],\"customStyleSheets\":[],\"separateInheritedMembers\":false,\"mergeImplicitExpectActualDeclarations\":false}"
    },
    {
      "fqPluginName": "org.jetbrains.dokka.versioning.VersioningPlugin",
      "serializationFormat": "JSON",
      "values": "{\"versionsOrdering\":[],\"olderVersions\":[],\"renderVersionsNavigationOnAllPages\":true}"
    }
  ],
  "modules": [
  ],
  "failOnWarning": false,
  "delayTemplateSubstitution": true,
  "suppressObviousFunctions": true,
  "includes": [
  ],
  "suppressInheritedMembers": false,
  "finalizeCoroutines": false
}

I'm using Dokkatoo 1.5.0

Update Dokkatoo to be built by and target Gradle 8.

This will be a breaking change, because currently Gradle does not provide an option to separate the Gradle version used to build a plugin from the Gradle version the plugin will target (see point 1, 2, 3 below).

• While updating check the code to make sure if there are any 'Unstable API' suppressions that can be removed.
• The Android Gradle plugin will have to be updated (to 7 or 8 I think) because the current version depends on Gradle features that are removed in v8).
• Update freeCompilerArgs configuration in build.gradle.kts files to use the newer provider-API friendly DSL
• Update dynamic plugin properties to use sealed interfaces & value classes
• Update the external link to Gradle types use Gradle's new Dokka site url("https://docs.gradle.org/${gradle.gradleVersion}/javadoc/")

1. There are 3rd party options to work around the hard-link (Nokee redistributed Gradle API artifacts), but I don't want to rely on non-standard workarounds.
2. There's also a confusing workaround in the Gradle docs, but the documentation is lacking. I've tried setting this up manually before, and it's a confusing mess.
3. Related issues:
   • gradle/gradle#25037
   • gradle/gradle#25132

When generating Dokkatoo docs it uses Gradle types. However, because the Gradle API is a compile-time dependency, apparently it's not added to the Dokka source set classpath

This results in 'Error class: unknown class' in the generated docs.

As a workaround I can manually add the compile classpath

// build.gradle.kts

dokkatoo {
  dokkatooSourceSets.configureEach {
    // workaround for https://github.com/adamko-dev/dokkatoo/issues/44
    classpath.from(configurations.compileClasspath.map { it.incoming.artifactView { lenient(true) }.artifacts.artifactFiles })
  }
}

But probably something needs to be fixed in DokkatooKotlinAdapter

Maybe add compileDependencyConfigurationName?

yield(compileDependencyConfigurationName)

I'm trying to add Dokkatoo generation to this Android project (see the feat/dokkatoo branch of my fork). However, running the :dokkatooGeneratePublicationHtml task results in the following Gradle error:

Could not determine the dependencies of task ':material3:dokkatooGenerateModuleHtml'.
> Could not resolve all task dependencies for configuration ':material3:releaseCompileClasspath'.
   > The consumer was configured to find a component for use during compile-time, preferably optimized for Android, as well as attribute 'com.android.build.api.attributes.BuildTypeAttr' with value 'release', attribute 'com.android.build.api.attributes.AgpVersionAttr' with value '8.1.1', attribute 'org.jetbrains.kotlin.platform.type' with value 'androidJvm'. However we cannot choose between the following variants of project :core:
       - Configuration ':core:releaseApiElements' variant android-classes-jar declares a component for use during compile-time, preferably optimized for Android, as well as attribute 'com.android.build.api.attributes.AgpVersionAttr' with value '8.1.1', attribute 'com.android.build.api.attributes.BuildTypeAttr' with value 'release', attribute 'org.jetbrains.kotlin.platform.type' with value 'androidJvm':
           - Unmatched attributes:
               - Provides attribute 'artifactType' with value 'android-classes-jar' but the consumer didn't ask for it
               - Provides attribute 'com.android.build.gradle.internal.attributes.VariantAttr' with value 'release' but the consumer didn't ask for it
               - Provides a library but the consumer didn't ask for it
               - Provides its elements packaged as a jar but the consumer didn't ask for it
       - Configuration ':core:releaseApiElements' variant android-lint declares a component for use during compile-time, preferably optimized for Android, as well as attribute 'com.android.build.api.attributes.AgpVersionAttr' with value '8.1.1', attribute 'com.android.build.api.attributes.BuildTypeAttr' with value 'release', attribute 'org.jetbrains.kotlin.platform.type' with value 'androidJvm':
           - Unmatched attributes:
               - Provides attribute 'artifactType' with value 'android-lint' but the consumer didn't ask for it
               - Provides attribute 'com.android.build.gradle.internal.attributes.VariantAttr' with value 'release' but the consumer didn't ask for it
               - Provides a library but the consumer didn't ask for it
               - Provides its elements packaged as a jar but the consumer didn't ask for it
       - Configuration ':core:releaseApiElements' variant android-lint-local-aar declares a component for use during compile-time, preferably optimized for Android, as well as attribute 'com.android.build.api.attributes.AgpVersionAttr' with value '8.1.1', attribute 'com.android.build.api.attributes.BuildTypeAttr' with value 'release', attribute 'org.jetbrains.kotlin.platform.type' with value 'androidJvm':
           - Unmatched attributes:
               - Provides attribute 'artifactType' with value 'android-lint-local-aar' but the consumer didn't ask for it
               - Provides attribute 'com.android.build.gradle.internal.attributes.VariantAttr' with value 'release' but the consumer didn't ask for it
               - Provides a library but the consumer didn't ask for it
       - Configuration ':core:releaseApiElements' variant android-lint-model-metadata declares a component for use during compile-time, preferably optimized for Android, as well as attribute 'com.android.build.api.attributes.AgpVersionAttr' with value '8.1.1', attribute 'com.android.build.api.attributes.BuildTypeAttr' with value 'release', attribute 'org.jetbrains.kotlin.platform.type' with value 'androidJvm':
           - Unmatched attributes:
               - Provides attribute 'artifactType' with value 'android-lint-model-metadata' but the consumer didn't ask for it
               - Provides attribute 'com.android.build.gradle.internal.attributes.VariantAttr' with value 'release' but the consumer didn't ask for it
               - Provides a library but the consumer didn't ask for it
       - Configuration ':core:releaseApiElements' variant android-lint-variant-dependencies-model declares a component for use during compile-time, preferably optimized for Android, as well as attribute 'com.android.build.api.attributes.AgpVersionAttr' with value '8.1.1', attribute 'com.android.build.api.attributes.BuildTypeAttr' with value 'release', attribute 'org.jetbrains.kotlin.platform.type' with value 'androidJvm':
           - Unmatched attributes:
               - Provides attribute 'artifactType' with value 'android-lint-variant-dependencies-model' but the consumer didn't ask for it
               - Provides attribute 'com.android.build.gradle.internal.attributes.VariantAttr' with value 'release' but the consumer didn't ask for it
               - Provides a library but the consumer didn't ask for it
       - Configuration ':core:releaseApiElements' variant android-lint-variant-dependencies-partial-results declares a component for use during compile-time, preferably optimized for Android, as well as attribute 'com.android.build.api.attributes.AgpVersionAttr' with value '8.1.1', attribute 'com.android.build.api.attributes.BuildTypeAttr' with value 'release', attribute 'org.jetbrains.kotlin.platform.type' with value 'androidJvm':
           - Unmatched attributes:
               - Provides attribute 'artifactType' with value 'android-lint-variant-dependencies-partial-results' but the consumer didn't ask for it
               - Provides attribute 'com.android.build.gradle.internal.attributes.VariantAttr' with value 'release' but the consumer didn't ask for it
               - Provides a library but the consumer didn't ask for it
       - Configuration ':core:releaseApiElements' variant android-manifest declares a component for use during compile-time, preferably optimized for Android, as well as attribute 'com.android.build.api.attributes.AgpVersionAttr' with value '8.1.1', attribute 'com.android.build.api.attributes.BuildTypeAttr' with value 'release', attribute 'org.jetbrains.kotlin.platform.type' with value 'androidJvm':
           - Unmatched attributes:
               - Provides attribute 'artifactType' with value 'android-manifest' but the consumer didn't ask for it
               - Provides attribute 'com.android.build.gradle.internal.attributes.VariantAttr' with value 'release' but the consumer didn't ask for it
               - Provides a library but the consumer didn't ask for it
       - Configuration ':core:releaseApiElements' variant android-renderscript declares a component for use during compile-time, preferably optimized for Android, as well as attribute 'com.android.build.api.attributes.AgpVersionAttr' with value '8.1.1', attribute 'com.android.build.api.attributes.BuildTypeAttr' with value 'release', attribute 'org.jetbrains.kotlin.platform.type' with value 'androidJvm':
           - Unmatched attributes:
               - Provides attribute 'artifactType' with value 'android-renderscript' but the consumer didn't ask for it
               - Provides attribute 'com.android.build.gradle.internal.attributes.VariantAttr' with value 'release' but the consumer didn't ask for it
               - Provides a library but the consumer didn't ask for it
       - Configuration ':core:releaseApiElements' variant android-symbol-with-package-name declares a component for use during compile-time, preferably optimized for Android, as well as attribute 'com.android.build.api.attributes.AgpVersionAttr' with value '8.1.1', attribute 'com.android.build.api.attributes.BuildTypeAttr' with value 'release', attribute 'org.jetbrains.kotlin.platform.type' with value 'androidJvm':
           - Unmatched attributes:
               - Provides attribute 'artifactType' with value 'android-symbol-with-package-name' but the consumer didn't ask for it
               - Provides attribute 'com.android.build.gradle.internal.attributes.VariantAttr' with value 'release' but the consumer didn't ask for it
               - Provides a library but the consumer didn't ask for it
       - Configuration ':core:releaseApiElements' variant jar declares a component for use during compile-time, preferably optimized for Android, as well as attribute 'com.android.build.api.attributes.AgpVersionAttr' with value '8.1.1', attribute 'com.android.build.api.attributes.BuildTypeAttr' with value 'release', attribute 'org.jetbrains.kotlin.platform.type' with value 'androidJvm':
           - Unmatched attributes:
               - Provides attribute 'artifactType' with value 'jar' but the consumer didn't ask for it
               - Provides attribute 'com.android.build.gradle.internal.attributes.VariantAttr' with value 'release' but the consumer didn't ask for it
               - Provides a library but the consumer didn't ask for it
               - Provides its elements packaged as a jar but the consumer didn't ask for it

(I've also experienced this issue with another project that is yet to be synced)

The version of Dokkatoo used is 2.0.0. Here's a Gradle Build Scan if necessary

For whatever reason, AndroidX classes (for e.g. androidx.browser.customtabs.CustomTabColorSchemeParams) produces Error class: unknown class in the resulting HTML output:

CustomTabColorSchemeParams also isn't clickable in the generated KDoc.

Source code for reference

I'm currently using 1.3.0, but this issue also appears to be present in 1.2.0 from some quick testing.

Checking the dokka_parameters.json file does show that the androidx.browser artifact is included in the classpath though:

{
  "moduleName": "browser-ktx",
  "moduleVersion": "0.0.1",
  "offlineMode": false,
  "failOnWarning": false,
  "sourceSets": [
    {
      "sourceSetId": {
        "scopeId": ":androidx:browser:browser-ktx",
        "sourceSetName": "main"
      },
      "displayName": "androidJvm",
      "classpath": [
        "[...]/.gradle/caches/modules-2/files-2.1/androidx.browser/browser/1.5.0/[...]/browser-1.5.0.aar",
        "[...]/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib-jdk8/1.8.21/[...]/kotlin-stdlib-jdk8-1.8.21.jar",
        "[...]/.gradle/caches/modules-2/files-2.1/androidx.core/core/1.1.0/[...]/core-1.1.0.aar",
        "[...]/.gradle/caches/modules-2/files-2.1/androidx.versionedparcelable/versionedparcelable/1.1.0/[...]/versionedparcelable-1.1.0.aar",
        "[...]/.gradle/caches/modules-2/files-2.1/androidx.collection/collection/1.1.0/[...]/collection-1.1.0.jar",
        "[...]/.gradle/caches/modules-2/files-2.1/androidx.annotation/annotation/1.2.0/[...]/annotation-1.2.0.jar",
        "[...]/.gradle/caches/modules-2/files-2.1/com.google.guava/listenablefuture/1.0/[...]/listenablefuture-1.0.jar",
        "[...]/.gradle/caches/modules-2/files-2.1/androidx.lifecycle/lifecycle-runtime/2.0.0/[...]/lifecycle-runtime-2.0.0.aar",
        "[...]/.gradle/caches/modules-2/files-2.1/androidx.lifecycle/lifecycle-common/2.0.0/[...]/lifecycle-common-2.0.0.jar",
        "[...]/.gradle/caches/modules-2/files-2.1/androidx.arch.core/core-common/2.0.0/[...]/core-common-2.0.0.jar",
        "[...]/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib-jdk7/1.8.21/[...]/kotlin-stdlib-jdk7-1.8.21.jar",
        "[...]/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib/1.8.21/[...]/kotlin-stdlib-1.8.21.jar",
        "[...]/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib-common/1.8.21/[...]/kotlin-stdlib-common-1.8.21.jar",
        "[...]/.gradle/caches/modules-2/files-2.1/org.jetbrains/annotations/13.0/[...]/annotations-13.0.jar",
        "[...]/.gradle/caches/modules-2/files-2.1/androidx.concurrent/concurrent-futures/1.0.0/[...]/concurrent-futures-1.0.0.jar",
        "[...]/.gradle/caches/modules-2/files-2.1/androidx.interpolator/interpolator/1.0.0/[...]/interpolator-1.0.0.aar",
        "[...]/Library/Android/sdk/platforms/android-33/android.jar"
      ],
      "sourceRoots": [
        "[...]/androidx-ktx-extras/androidx/browser/browser-ktx/src/main/kotlin"
      ],
      "dependentSourceSetIds": [
      ],
      "samples": [
      ],
      "includes": [
      ],
      "reportUndocumented": true,
      "skipEmptyPackages": true,
      "skipDeprecated": false,
      "jdkVersion": 8,
      "sourceLinks": [
        {
          "localDirectory": "[...]/androidx-ktx-extras/androidx/browser/browser-ktx/src/main/kotlin",
          "remoteUrl": "https://github.com/EdricChan03/androidx-ktx-extras/tree/main/androidx/browser/browser-ktx/src/main/kotlin",
          "remoteLineSuffix": "#L"
        }
      ],
      "perPackageOptions": [
      ],
      "externalDocumentationLinks": [
        {
          "url": "https://developer.android.com/reference/kotlin/",
          "packageListUrl": "https://developer.android.com/reference/kotlin/package-list"
        },
        {
          "url": "https://developer.android.com/reference/kotlin/",
          "packageListUrl": "https://developer.android.com/reference/kotlin/androidx/package-list"
        },
        {
          "url": "https://docs.oracle.com/javase/8/docs/api/",
          "packageListUrl": "https://docs.oracle.com/javase/8/docs/api/package-list"
        },
        {
          "url": "https://kotlinlang.org/api/latest/jvm/stdlib/",
          "packageListUrl": "https://kotlinlang.org/api/latest/jvm/stdlib/package-list"
        }
      ],
      "enableKotlinStdLibDocumentationLink": true,
      "enableJdkDocumentationLink": true,
      "suppressedFiles": [
      ],
      "analysisPlatform": "jvm",
      "documentedVisibilities": [
        "PUBLIC"
      ]
    }
  ],
  "pluginsClasspath": [
    "[...]/.gradle/caches/modules-2/files-2.1/org.jetbrains.dokka/dokka-analysis/1.8.10/[...]/dokka-analysis-1.8.10.jar",
    "[...]/.gradle/caches/modules-2/files-2.1/org.jetbrains.dokka/templating-plugin/1.8.10/[...]/templating-plugin-1.8.10.jar",
    "[...]/.gradle/caches/modules-2/files-2.1/org.jetbrains.dokka/dokka-base/1.8.10/[...]/dokka-base-1.8.10.jar",
    "[...]/.gradle/caches/modules-2/files-2.1/org.jetbrains.dokka/kotlin-analysis-intellij/1.8.10/[...]/kotlin-analysis-intellij-1.8.10.jar",
    "[...]/.gradle/caches/modules-2/files-2.1/org.jetbrains.dokka/kotlin-analysis-compiler/1.8.10/[...]/kotlin-analysis-compiler-1.8.10.jar",
    "[...]/.gradle/caches/modules-2/files-2.1/org.freemarker/freemarker/2.3.31/[...]/freemarker-2.3.31.jar",
    "[...]/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlinx/kotlinx-html-jvm/0.8.0/[...]/kotlinx-html-jvm-0.8.0.jar"
  ],
  "pluginsConfiguration": [
    {
      "fqPluginName": "org.jetbrains.dokka.base.DokkaBase",
      "serializationFormat": "JSON",
      "values": "{\"customAssets\":[],\"customStyleSheets\":[],\"separateInheritedMembers\":false,\"mergeImplicitExpectActualDeclarations\":false}"
    },
    {
      "fqPluginName": "org.jetbrains.dokka.versioning.VersioningPlugin",
      "serializationFormat": "JSON",
      "values": "{\"versionsOrdering\":[],\"olderVersions\":[],\"renderVersionsNavigationOnAllPages\":true}"
    }
  ],
  "delayTemplateSubstitution": false,
  "suppressObviousFunctions": true,
  "includes": [
  ],
  "suppressInheritedMembers": false,
  "finalizeCoroutines": false,
  "modules": [
  ]
}

Sources

• GitHub repository
• Precompiled script which configures Dokkatoo

Additional info

Curiously enough, the annotations seem to work as expected though... 🤔

Proposal

Adjust Dokkatoo so that it downloads any package list files using Gradle based mechanisms (e.g. TextResource).

Benefits

• Improve runtime speed by removing a remote network call during Dokka Generator
• Improve reproducibility (less dynamic behaviour during runtime)
• Consolidate network proxy mechanisms, so proxy settings only have to be set for Gradle configurations

Detail

It's possible to pass a package list URL to Dokka Generator, which will then download the file ad-hoc using java.net.URL.

https://github.com/Kotlin/dokka/blob/d680b14ee033da5b7edf2406c35a93583a8f8eed/plugins/base/src/main/kotlin/resolvers/shared/PackageList.kt#L26-L34

Instead of passing a network address, a file address can be passed instead.

/**
* Specifies the exact location of a `package-list` instead of relying on Dokka
* automatically resolving it. Can also be a locally cached file to avoid network calls.
*
* Example:
*
* ```kotlin
* rootProject.projectDir.resolve("serialization.package.list").toURL()
* ```
*/
@Optional
@Input
val packageListUrl: Property<URL> = project.objects.property()

Related

• Kotlin/dokka#3026

Gradle recommends using typesafe attributes to share files. However, these are fundamentally bugged and will not work in some situations.

I will implement a workaround, but I am opening this issue to track a real fix, dependent on whether Gradle can acknowledge and fix the issue.

This issue might be the cause of #165 and #170.

Thank you @kelvSYC for the report and reproducer! #211

E.g., I want separate Dokka html report/site for all "api" modules for general API documentation for the app.
And a different Dokka report for "all android device tests" to document what tests do.
And a different Dokka report for "all unit device tests" to document what tests do.
And a different one for "test framework which is a bunch of different modules as well a subset of a module".

Build scan comparisons

Example on my machine:

$ cat libraries/apollo-adapters/build/dokka-config/html/dokka_parameters.json | head -n 20
{
  "moduleName": "apollo-adapters",
  "moduleVersion": "4.0.0-dev.3-SNAPSHOT",
  "offlineMode": false,
  "failOnWarning": false,
  "sourceSets": [
    {
      "sourceSetId": {
        "scopeId": ":apollo-adapters",
        "sourceSetName": "appleMain"
      },
      "displayName": "apple",
      "classpath": [
        "/Users/mbonnin/git/apollo-kotlin/libraries/apollo-api/build/classes/kotlin/iosArm64/main/klib/apollo-api.klib",
        "/Users/mbonnin/git/apollo-kotlin/libraries/apollo-annotations/build/classes/kotlin/iosArm64/main/klib/apollo-annotations.klib",
        "/Users/mbonnin/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlinx/kotlinx-datetime-iosarm64/0.4.0/8f2e032c52e3e59cf8e63213609007f80bdb6748/kotlinx-datetime.klib",
        "/Users/mbonnin/.gradle/caches/modules-2/files-2.1/com.squareup.okio/okio-iosarm64/3.2.0/a4351920c1dc049812599064a73596d245aa12c7/okio.klib",
        "/Users/mbonnin/.gradle/caches/modules-2/files-2.1/com.benasher44/uuid-iosarm64/0.6.0/719bcb24170ab712e6b31de02a6d6ad863bc926c/uuid.klib",
        "/Users/mbonnin/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib/1.6.21/11ef67f1900634fd951bad28c53ec957fabbe5b8/kotlin-stdlib-1.6.21.jar",
        "/Users/mbonnin/.gradle/caches/modules-2/files-2.1/org.jetbrains/annotations/24.0.1/13c5c75c4206580aa4d683bffee658caae6c9f43/annotations-24.0.1.jar",

Not really sure how to make the /Users/mbonnin/... relative. Maybe the project dependencies can be relative to the root project but the external ones sound tricky

Hi!

I'm using the version 2.0.0. In CI, I'm seeing:

* What went wrong:
Execution failed for task ':compat:compat-ktor:dokkatooGeneratePublicationHtml'.
> A failure occurred while executing dev.adamko.dokkatoo.workers.DokkaGeneratorWorker
   > Java heap space

How much memory should I configure? How can I configure it?

Similar to #66

Build scan comparisons

On my machine:

$ cat libraries/apollo-adapters/build/dokka-config/html/module_descriptor.json

{
  "name": "apollo-adapters",
  "sourceOutputDirectory": "/Users/mbonnin/git/apollo-kotlin/libraries/apollo-adapters/build/dokka-module/html",
  "includes": [
  ],
  "modulePath": "apollo-adapters"
}

This one sounds a tiny bit easier to fix

"As a Java library/application author I want to use Dokkatoo to generate documentation. I don't have any Kotlin code."

Dokka can generate docs for pure Java code. But, when I apply Dokkatoo to a pure Java project, it doesn't automatically set up Dokkatoo.

It should be pretty easy to do.

• Update DokkatooJavaAdapter to scrape source sets and automatically create them, similarly to DokkatooKotlinAdapterhttps://github.com/adamko-dev/dokkatoo/blob/v2.2.0/modules/dokkatoo-plugin/src/main/kotlin/adapters/DokkatooKotlinAdapter.kt
• Make sure if a project has Kotlin & Java, then Dokkatoo doesn't get confused.
• Update docs to say "generate docs for Kotlin and/or Java"
• Add an example projects
  • single module
  • multi-module (based on ./examples/multimodule-example/dokkatoo?)

Can you please add a sample how to use a Dokka plugin, like the mermaid plugin?
https://github.com/glureau/dokka-mermaid

With dokka, all you need is to add it to the top level project:

dependencies {
  dokkaPlugin("com.glureau:html-mermaid-dokka-plugin:0.6.0")
}

I am facing a compilation error when generating the Dokka output. However, the problem does not appear when compiling the project normally (./gradlew check).

It seems Dokka cannot find the standard library, and complains about many symbols from it:

e: file:///…/src/commonMain/kotlin/Parameters.kt:46:31 Unresolved reference: HashMap
e: file:///…/src/commonMain/kotlin/Parameters.kt:120:3 Unresolved reference: JvmInline
e: file:///…/commonMain/kotlin/Parameters.kt:141:4 Unresolved reference: require
e: file:///…/src/commonMain/kotlin/Parameters.kt:141:17 Unresolved reference: isNotBlank

Reproduction:

• Clone the repository https://gitlab.com/opensavvy/spine.git
• Checkout commit a5dede751c40d143b671b12e33df2ac769e3fdfd
• Run ./gradlew check ← passes
• Run ./gradlew :dokkatooGeneratePublicationHtml ← fails with compilation error

The full output of the failed execution is available here.

Are the docs at https://kotlinlang.org/docs/dokka-gradle.html#build-javadoc-jar outdated? I cannot seem to find a task named dokkaHtml or dokkaJavadoc. Are these "wrapper tasks" even still needed, or are they built-in as dokkatooGenerateModuleHtml and dokkatooGenerateModuleJavadoc respectively by now?