Dokka: How to use dokka on a subproject?

[jnizet]

Question

I've read the blog post about dokka 1.4.0-rc and tried to apply it on a project of mine. The blog post asked for feedback and linked to the github issues page, so this is more a large feedback on my experience than a question. Sorry for that. I hope it will be useful.

You can have a look at the structure of the project here: https://github.com/Ninja-Squad/globe42

It's really simple:

• globe42: empty root project
  
  
  
  • backend: spring boot sub-project using Kotlin (JVM), which is thus the only project that dokka should care about.
  
  
  • frontend: JS sub-project having nohing to do with Kotlin
  
  

I first tried to add the new dokka plugin only to the backend sub-project (all I had to do was change kotlin version and the version of the dokka plugin that was already applied).

Then I ran the task dokkaHtml, and inspected the content of backend/build/dokka/html

Expectation: find an index.html file there.
Reality: no index.html file.

There is a backend subdirectory containing an index.html though. But that's ugly: it means that I can't serve the documentation at the root of a web server. the index.html page must be served from /backend/index.html, and it fetches files from ...

I then try to open this index.html file

Expectation: find a list of packages in the left bar
Reality: the left bar is completely empty

Looking at the issues, I see that it needs to be served over http. So I run http-server from the backend/build/dokka/html directory and navigate to http://localhost:8080/backend.

Expectation: have a list of packages in the left bar
Reality: the left bar contains a single link: "globe42". When I click it, it goes to http://localhost:8080/globe42/index.html, which doesn't exist, resulting in a 404.

If I go back the the main page and click on a package (let's say org.globe42.web.activities), then finally the left sidebar populates itself with a package tree. The main section shows the content of the package. The first one for example (ActivityTypeController), is annotated with @RestController, which is a Spring annotation.

Expectation: See the annotation as @RestController
Reality: The annotation is displayed as @RestController(), which is not very idiomatic, IMHO

Expectation: the annotation shouldn't be a link, since I never instructed dokka to link to the Spring javadoc
Reality: it's a link. If I click on it, it reloads the current page.

Expectation: the breadcrumbs at the dop of the page should allow me to navigate to the parent package org.globe42.web.
Reality: it does not. The link shows the full pakage name, but clicking anywhere just reloads the page. The link is thus useless.

Then I tried to sole the left bar issues by applying the dokka plugin to the root project. Maybe that's what I'm supposed to do. So I add the dokka plugin to the root project, and run ./gradlew tasks

Expectation: the new dokka tasks should be listed and documented
Reality: the new tasks (dokkaHtmlCollector, dokkaHtmlMultimodule, etc.) are listed, but with no description.

I try running the dokkaHtmlCollector task.

Expectation: it runs doka on the unique kotlin subproject I have and collect the output in the root project
Reality: it fails with the error:

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':dokkaHtmlCollector'.
> org/jetbrains/kotlin/gradle/dsl/KotlinProjectExtension

Sure enough: the root project is not a Kotlin project. It's only there to aggregate multiple projects. let's pretend its is a Kotlin JVM project (although it shouldn't be), and add the kotlin JVM plugin to the root project. Now running dokkaHtmlCollector succeeds. I inspect the content of build/dokka/htmlCollector.

Expectation: find an index.html file there
Reality: once again: no index.html file.

The index.html file is, once again, in the backend directory. There is no globe42 directory. But at least, if I serve the htmlCollector directory and go to http://localhost:8080/backend, then the left side bar is correctly populated.

Lets' do the same experiment with the other task: dokkaHtmlMultimodule.

Expectation: it works even if the root project is not a Kotlin project
Reality: just as for dokkaHtmlCollector, it doesn't

Once I've made the root project a Kotlin JVM project( although it shouldn't be), then the first attempt leads to

Daemon will be stopped at the end of the build after running out of JVM memory

I've only ran dokka tasks, and it's a tiny project. It shouldn't lead to OOM IMHO.

Second attempt, a new daemon is started, and the task goes further, but fails with

Missing documentation file for module backend: /Users/jb/projects/globe42/backend/README.md

IMHO, I shouldn't have to provide a README.md file. If there is none, then dokka should simply assume it's there but empty.

I add an empty README.md file, and run the task again. It succeeds. i inspect the content of build/dokka/htmlMultimodule.

Expectation: find an index.html file there
Reality: once again: no index.html file.

This time there is no index.html file at all. The README of dokka says: "creates a toplevel page (based on the documentationFile) with links to all generated (sub)documentations", but I don't see any such page being created.

Installation

• Operating system: macOS
• Build tool: Gradle v6.5.1
• Dokka version: 1.4.0-rc

[sellmair]

Thank you so much for the detailed and well-structured feedback 😍

• Some points that you addressed are known issues to us and your feedback further increases our confidence of our plans to fix them.
• Some points need further investigation: I will be checking out your project asap
• Some points are already fixed (hopefully)

I will try to provide a more detailed answer after checking out your project 👍

[sdeleuze]

:+1: for @jnizet remarks, and the lack of proper index.html file at the root of the doc generated by ./gradlew clean dokkaHtmlMultiModule is a blocker for Spring Framework 5.3 being able to use Dokka 1.4, so I hope this will be fixed in Dokka 1.4.20 otherwise I think we won't be able to use it.

To see concretely the result, clone https://github.com/sdeleuze/spring-framework, checkout dokka branch and run ./gradlew clean dokkaHtmlMultiModule. The resulting doc is in build/docs/kdoc with no index.html at the root, search seems to be broken, etc.

Thanks in advance for your help.

[czyzby]

We've ran into similar issues in KTX. See https://github.com/libktx/ktx/issues/303 and https://github.com/libktx/ktx/pull/316.

OOM errors can be avoided by adding this setting to gradle.properties: org.gradle.jvmargs=-Xmx1024m. While this is definitely a workaround, this should be enough to generate the documentation for medium projects.

As for the lack of a top-level index.html file, we eventually decided to generate a redirection page:

<!DOCTYPE HTML>
<html lang="en-US">
    <head>
        <meta charset="UTF-8">
        <meta http-equiv="refresh" content="0; url=yourProject/">
        <script type="text/javascript">
            window.location.href = "yourProject/"
        </script>
        <title>Documentation</title>
    </head>
    <body>
        If you are not redirected automatically, follow <a href="yourProject/">this link</a>.
    </body>
</html>

[sdeleuze]

FYI I had to postpone the usage of Dokka 1.4 in Spring Framework 5.3 due to these issues raised by @jnizet.

[sellmair]

@Kordyjan I assigned this to you, just to keep you in the loop ☺️