Dokka Gradle plugin doc update #4354

AlejandraPedroza · 2025-11-17T19:54:58Z

This PR updates all the documents relevant to Dokka Gradle plugin v2, now that with Dokka 2.1.0, the DGP v2 is enabled by default:

KT-72372 Update Dokka's documentation on kotlinlang for DPGv2
KT-77370 Fix code block in Dokka docs
KT-78276 DGPv2: document dokkaJavadoc

adam-enko · 2025-11-18T10:29:27Z

docs/topics/formats/dokka-html.md

 <tab title="Groovy" group-key="groovy">

 ```groovy
 import org.jetbrains.dokka.gradle.DokkaTask

 tasks.withType(DokkaTask.class) {
    String dokkaBaseConfiguration = """
    {
      "customAssets": ["${file("assets/my-image.png")}"],
      "customStyleSheets": ["${file("assets/my-styles.css")}"],
      "footerMessage": "(c) 2022 MyOrg"
      "separateInheritedMembers": false,
      "templatesDir": "${file("dokka/templates")}",
      "mergeImplicitExpectActualDeclarations": false
    }
    """
    pluginsMapConfiguration.set(
            // fully qualified plugin name to json configuration
            ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration]
    )
 }
 ```


The Groovy DSL example should be updated too. Or maybe removed?

@whyoleg What do you think we should do here?

Let's update them. Groovy is still there, and other documentation on kotlinlang provides examples that use it.

adam-enko · 2025-11-18T10:40:59Z

docs/topics/formats/dokka-markdown.md

What about just removing the Markdown and Jekyll formats from the docs?

We intentionally didn't include them in the v2 release. They've always been alpha, and are missing feature parity with the HTML format.

The new docs suggest users manually implement the plugins, but this can be a complicated task. Copy-pasting code is what makes Gradle buildscripts more complicated and hard to maintain. The code snippets also suggest using InternalDokkaGradlePluginApi - something we should be discouraging.

Instead, the docs could have a 'third party supported formats' page? Like Serialization has? https://github.com/Kotlin/kotlinx.serialization/blob/v1.9.0/formats/README.md#other-community-supported-formats

TBH, I don't know :)
It was my idea to include those snippets, as it's now still possible, as we still publish those artifacts.

There is still some interest in markdown (#4021).
Let me think a bit about it

Let's move all Jekyll and Markdown modules (both dokka-plugins and gradle-plugins) into Dokkatoo, and they can be community supported?

@whyoleg @adam-enko Please let me know when you have a final decision here to update the docs accordingly (:

Maybe we could move the documentation to the plugins' readme?

Maybe we could move the documentation to the plugins' readme?

Yes! I do love this idea. Let's remove dokka-markdown and move it's content to plugin-gfm and plugin-jekyll respectively.
Thanks @atyrin!

Let's move all Jekyll and Markdown modules (both dokka-plugins and gradle-plugins) into Dokkatoo, and they can be community supported?

At this point, I don't think it's worth the effort.

docs/topics/dokka-get-started.md

docs/topics/dokka-gradle-troubleshooting-md.md

docs/topics/dokka-plugins.md

adam-enko · 2025-11-18T11:01:34Z

docs/topics/formats/dokka-html.md


-HTML is Dokka's default and recommended output format. It is currently in Beta and approaching the Stable release.
-
+HTML is Dokka's default and recommended output format. 


Maybe we should fluff this up a bit? Something to entice users to use HTML?

"HTML is pretty, supports KMP, Android, Java. It's fully featured and is WAY better than Javadoc. It can document single projects, or large multi-modules."

I don't think that we should do comparison with Javadoc here. For me It feels weird when some official language documentation says, that something is better (WAY better) than in the other language.
I'm just, that this is how it will be interpreted, and not, for comparison of Dokka's formats (HTML vs Javadoc).
We can document some limitations (KMP, multi-module) on the Javadoc page, though.

Yeah, I agree. (I didn't mean for my suggestion to be literal, I was making a bit of a joke.)

Added clarifications in both HTML and Javadoc, avoiding comparisons and adjectives.

docs/topics/formats/dokka-html.md

adam-enko · 2025-11-18T11:07:44Z

docs/topics/formats/dokka-html.md

+  * `dokkaGeneratePublicationHtml` to generate documentation only in HTML format. 
+  * `dokkaGenerate` to generate documentation in [all available formats based on the applied plugins](dokka-gradle.md#configure-documentation-output-format).


I think we can refine this a bit. At least, dokkaGenerate should be first.

Info dump:

dokkaGenerate should be the general task that most users use. It's quick and easy to use, and (if using HTML + IntelliJ) logs a clickable link to the generated docs.

dokkaGeneratePublicationHtml is specifically only for if users want to use the generated files in other tasks (e.g. upload the files to a server, move them into a GitHub Pages dir, or package them into a javadoc.jar). It has an @OutputDirectory, so if it's used in Gradle tasks then Gradle can infer the task dependencies.

We decided to 'hide' dokkaGeneratePublicationHtml from the Gradle task groups because it's not an 'every day run task', and we didn't want to present two similar tasks to confuse users.

whyoleg

First round of review :)

docs/topics/runners/dokka-gradle.md

docs/topics/dokka-plugins.md

whyoleg · 2025-11-18T13:06:36Z

docs/dokka.tree

 <?xml version='1.0' encoding='utf-8'?>
 <!DOCTYPE instance-profile SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
-<instance-profile id="dokka" name="dokka" start-page="dokka-introduction.md">
+<instance-profile id="dokka" name="dokka" start-page="dokka-gradle-troubleshooting-md.md">


Is this change intentional? Or what it affects? :)

Yes, I took the Troubleshooting out of the migration guide. From what I see, the troubleshooting information is useful for DGP v2, and now that DGP v2 is the default, this information is useful for everyone using DGP with the defaul version, not only related to migration. Is this correct?

Yeah, I agree, having a separate page for this is really nice!
My question was mostly about its usage as a start-page attribute value. I don't fully understand what it affects, but it appears to be wrong.

whyoleg · 2025-11-18T13:12:14Z

docs/topics/formats/dokka-html.md


-HTML is Dokka's default and recommended output format. It is currently in Beta and approaching the Stable release.
-
+HTML is Dokka's default and recommended output format. 


I don't think that we should do comparison with Javadoc here. For me It feels weird when some official language documentation says, that something is better (WAY better) than in the other language.
I'm just, that this is how it will be interpreted, and not, for comparison of Dokka's formats (HTML vs Javadoc).
We can document some limitations (KMP, multi-module) on the Javadoc page, though.

whyoleg · 2025-11-18T13:18:17Z

docs/topics/formats/dokka-markdown.md

TBH, I don't know :)
It was my idea to include those snippets, as it's now still possible, as we still publish those artifacts.

There is still some interest in markdown (#4021).
Let me think a bit about it

atyrin · 2025-11-19T16:11:19Z

docs/topics/runners/dokka-gradle.md


-<tabs group="build-script">
-<tab title="Kotlin" group-key="kotlin">
+The syntax of `build.gradle.kts` files differs from regular `.kt` 


Do we really want to provide snippets for "precompiled" plugins (the tab called Kotlin)? I think it is unnecessary, since everywhere we suggest using convention plugins with build scripts.

Also, naming is a little bit confusing. Not sure that everyone will associate "Gradle configuration file" with kts and not "Kotlin".

What do you think? @adam-enko
Asking him, as this was initially suggested by him.

I think the reason for this was based on some user feedback:

dokkaSourceSets.main {}: main could not be found. What to use when you want to use includes?

It's tricky, because the gradle.kts example assumes the Kotlin DSL generated accessors are present. They might not be available for binary plugins (like CustomPlugin).

We could update the .gradle.kts example to use strings to access the data, like dokka.dokkaPublications.named("html"), but this isn't ideal.

I suggested adding a binary plugin (but a very weak suggestion, it was more of a potential option to consider), because that doesn't have the dsl accessors. But I'm not sure it's that helpful to users.

another idea is to have a commented out example next to the accessor with the alternative:

// build.gradle.kts dokka { dokkaSourceSets.main { // or dokkaSourceSets.named("main") { // ... } pluginsConfiguration.html { // or pluginsConfiguration.named<org.jetbrains.dokka.gradle.engine.plugins.DokkaHtmlPluginParameters>("html") { // ... } }

Is the problem with missed accessors applicable for KGP? We don't have .kt samples there.

Is the problem with missed accessors applicable for KGP? We don't have .kt samples there.

KGP tries to minimise the need for generated accessors. For example, kotlin.sourceSets.nativeMain {} - the nativeMain accessor is defined in KGP, it's not generated.

docs/topics/runners/dokka-gradle.md

atyrin · 2025-11-19T16:40:34Z

docs/topics/runners/dokka-gradle.md

-    tasks.dokkaHtmlPartial {
-        outputDirectory.set(layout.buildDirectory.dir("docs/partial"))
-    }
+Follow the next steps to configure your multi-module project without convention plugins.


I don't get this part. It should be the next steps without convention plugins, but then we start describing how to create a convention plugin.

"Without" means that require one, that's why we have the instructions to create one. I've updated it, hopefully it is clearer.

Ah, it's about projects that don't have convention plugins yet, and we show how to add them. Thanks.

But then the two sections with/without are not so different. In the first one we describe the project structure and explain how to do it. And in the second it's almost the same, but it is described in Gradle documentation that we refer to.

docs/topics/runners/dokka-gradle.md

This PR updates all the documents relevant to Dokka Gradle plugin v2 # Conflicts: # docs/topics/dokka-get-started.md # docs/topics/dokka-plugins.md # docs/topics/formats/dokka-html.md # docs/topics/formats/dokka-markdown.md

whyoleg

Nice!

whyoleg · 2025-11-20T12:52:56Z

docs/topics/runners/dokka-gradle.md

-{style="note"}
+The Dokka Gradle plugin comes with [HTML](dokka-html.md) and [Javadoc](dokka-javadoc.md) output formats 
+built in. 
+Additionally, you can manually enable the [Markdown](dokka-markdown.md) format.


Let's remove all mentions of markdown formats then from the documentation, as we decided to move those into readme's of plugins.

whyoleg · 2025-11-20T12:54:44Z

docs/topics/runners/dokka-gradle.md

+> Successful integration with tools that accept Javadoc as input is not guaranteed. 
+> Use it at your own risk.
+>
+{style="note"}


Curious: should it be a note or a warning? warning was used previously on javadoc page

whyoleg · 2025-11-20T13:17:08Z

docs/topics/formats/dokka-html.md

-  {style="note"}
-
+* For [Gradle](dokka-gradle.md#generate-documentation), run the following tasks: 
+  * `dokkaGenerate` to generate documentation in [all available formats based on the applied plugins](dokka-gradle.md#configure-documentation-output-format).


At this point, I've realized that we might have done something wrong with DGPv2 tasks API...

By default, for the HTML format we have the following tasks:

dokkaGenerate - shown in IDE, run's all dokkaGenerate*

dokkaGenerateHtml - shown in IDE, run's dokkaGeneratePublicationHtml (just an alias)

dokkaGenerateModuleHtml - hidden in IDE, internal task

dokkaGeneratePublicationHtml - hidden in IDE, REAL task, which runs Dokka, and which users might need to depend on in code (for outputs)

Now comes the question: how that happened that we have dokkaGenerateHtml and dokkaGeneratePublicationHtml which are just aliases, but one users will see in IDE, but the other one, they need to use in code?

@adam-enko, am I missing something?

sorry, I don't get the question, could you rephrase it?

The question is, did I correctly describe the current situation with tasks?

However, what I wanted to highlight is that there should be only one task to run the Dokka generation for a specific format. We have two of them (dokkaGenerateHtml and dokkaGeneratePublicationHtml) which do the same thing, but for some reason, we show dokkaGenerateHtml in the IDE (dokka group), but users need to use dokkaGeneratePublicationHtml in Gradle scripts if they want to get their output. There are no other differences between those tasks.

It appears that, at some point, we simply missed this... And as DGPv2 is now stable, we can't change it.

What I propose, then, is that we consider dropping the usage of dokkaGenerateHtml in documentation/errors/etc and hiding it in the IDE, while using dokkaGeneratePublicationHtml everywhere, thereby showing it in the IDE. E.g., soft deprecation of dokkaGenerateHtml task.
We can't do otherwise, as users might already rely on the fact that dokkaGeneratePublicationHtml has outputs.
It's a bit sad that it happened after a stable release, but it feels better than explaining the differences.

Okay, thanks, I see your point.

I don't think it's that much of a mistake. It's just a different approach to Gradle plugin development.

Speaking generally, it's a good idea to keep the API surface small, and part of that is only exposing lifecycle tasks. It helps give us some flexibility in the future, in case we need to modify the actual worker tasks (e.g. move them from DGP into KGP). It also helps guide users away from task-based configuration and towards using dokka {}.

That said, in this instance, the difference between the two tasks is quite subtle. It would make sense to update dokkaGenerateHtml to be the user-facing task that provides the output (e.g. it can be used in a JAR task). We can deprecate or de-prioritise dokkaGeneratePublicationHtml if necessary. There are a few paths for migration.

Another thought: As far as I can tell, the only reason dokkaGeneratePublicationHtml needs to be documented is because DGP doesn't have a dokkaGenerateHtmlJar. If we had that, then we could expose that as the public task and keep the other tasks as 'soft' internal?

whyoleg · 2025-11-20T13:19:34Z

docs/topics/runners/dokka-gradle.md

-```
+
+    dependencies {
+        implementation("org.jetbrains.dokka:dokka-gradle-plugin:2.0.0")


We should probable recheck all documentation files for 2.0.0 and 2.1.0 and replace them with %dokkaVersion%

whyoleg · 2025-11-20T13:23:15Z

docs/topics/dokka-module-and-package-docs.md

@@ -1,15 +1,15 @@
-[//]: # (title: Module documentation)
+[//]: # (title: Subproject documentation)


I'm not sure, that we need to change naming here.
Dokka still uses module for defining those parameters.
We do also have moduleVersion and moduleName in DSL.

whyoleg · 2025-11-20T13:24:54Z

docs/topics/dokka-plugins.md

 | [MermaidJS HTML plugin](https://github.com/glureau/dokka-mermaid)                                                                  | Renders [MermaidJS](https://mermaid-js.github.io/mermaid/#/) diagrams and visualizations found in KDocs      |
 | [Mathjax HTML plugin](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-mathjax)                        | Pretty prints mathematics found in KDocs                                                                     |
-| [Kotlin as Java plugin](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-kotlin-as-java)              | Renders Kotlin signatures as seen from Java's perspective                                                    |
+| [Kotlin as Java plugin](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-kotlin-as-java)               | Renders Kotlin signatures as seen from Java's perspective                                                    |


After we move markdown documentation to GH, we can add links to them here

AlejandraPedroza requested review from adam-enko, atyrin and whyoleg November 17, 2025 19:55