I don't understand how the all-modules-page plugin...

# dokka

[CLOVIS]

I don't understand how the all-modules-page plugin works. Looking at the source of the org.jetbrains.dokka.gradle.formats.DokkaHtmlPlugin , there is a check but no configuration at all. The Javadoc plugin doesn't aggregate modules, and the other formats haven't been migrated to the Gradle plugin?

[Adam S]

hey, what are you interested in finding out about?

The all-modules-page-plugin doesn't have any configuration, so there's not much DGP can do.

The all-modules-page-plugin just automatically aggregates all partial Dokka modules whenever it's added as a Dokka plugin. The main workings of it are in org.jetbrains.dokka.allModulesPage.AllModulesPagePlugin

[CLOVIS]

Looking at :gfm-template-processing , :jekyll-template-processing , etc, there seems to be a quite a bit that needs to happen at aggregation time? Most notably, resolving cross-module links.

[CLOVIS]

I'm trying to follow the advice from this issue by creating an aggregation plugin, but I can't find how the HTML modules are actually aggregated, and I don't think the other formats are supported by the Gradle plugin?

[Adam S]

Hmm I can only really rubber duck here, because I haven't looked into how the formats actually work.

I don't think Dokka's GFM and Jekyll formats support multimodule aggregation (i.e. combining multiple subprojects).

[Adam S]

I don't think the other formats are supported by the Gradle plugin?

Yeah, that's right

[Adam S]

oh weird, I do see allModulesPagePlugin referenced in org.jetbrains.dokka.gfm.templateProcessing.JekyllTemplateProcessingPlugin. I wonder what that's about

[Adam S]

so, could you say a bit more about the broken hyperlinks https://gitlab.com/opensavvy/automation/dokka-material-mkdocs/-/issues/18?

[CLOVIS]

You can observe them here: https://opensavvy.gitlab.io/ktmongo/docs/api/-kotlin%20-b-s-o-n%20%E2%80%A2%20-based%20on%20the%20official%20-mongo-d-b%20implementation/index.html

Any link in a module page to another page of the documentation is broken
Any link anywhere else (including in package pages, etc) works

[CLOVIS]

It's very likely that this is caused by my fiddling with the LocationProvider (as mentioned in the GH issue). From what I understand, it's all-modules-page's job to reorganize pages and fix cross-module links? But I don't understand how to tell it to do it

[CLOVIS]

I also don't understand how the HTML format configures all-modules-page

[Adam S]

okay so I see that the link to the package does 404, but the actual link seems to be generated correctly

[Adam S]

it's odd that the link contains descriptive text, and I see that was discussed in the GitHub issue

[Adam S]

when aggregated multiple modules the HTML plugin has two phase:

1. generate partial modules (links to classes/functions to code in other projects aren't fully computed, they're guessed)
2. aggregate 1+ partial modules (the guessed links are finalised)
The all-modules-pages plugin has no configuration. Whenever it's added as a Dokka plugin, it's activated. There's not even a way to enable/disable it. So step 1 cannot have all-modules-pages as a Dokka plugin, while step 2 must have it. (And just to note, there's a difference between a Dokka plugin being enabled as a plugin vs a Dokka plugin being available on the Dokka classpath during generation).

Did you set up something similar?

[CLOVIS]

but the actual link seems to be generated correctly

It's not, the file is <module>/index.html. It currently contains a relative link <module>/foo.html , which therefore leads to <module>/<module>/foo.html .

The link in the file should be foo.html , since that page is in the same directory as the module page.

[Adam S]

The actual page url is

<https://opensavvy.gitlab.io/ktmongo/docs/api/-kotlin> -b-s-o-n • -based on the official -mongo-d-b implementation/opensavvy.ktmongo.bson.official/index.html

But the (incorrect) generated link is

<https://opensavvy.gitlab.io/ktmongo/docs/api/-kotlin> -b-s-o-n • -based on the official -mongo-d-b implementation/-kotlin -b-s-o-n • -based on the official -mongo-d-b implementation/opensavvy.ktmongo.bson.official/index.html

The -kotlin -b-s-o-n • -based on the official -mongo-d-b implementation part is repeated twice, so I guess either the location provider is accidentally duplicating the module name, or the actual Documentable has incorrect data?

[CLOVIS]

Did you set up something similar?

I did not. My current setup is essentially a copy-paste of the :gfm plugin, without the template processing part.

[CLOVIS]

so I guess either the location provider is accidentally duplicating the module name, or the actual Documentable has incorrect data?

My best guess is that I broke the LocationProvider while modifying it, making it asymmetric (in one direction and the other it gives differents paths)

[CLOVIS]

From what I understand though, the paths should be generated during the aggregation, and I shouldn't need to edit the LocationProvider at all?

[Adam S]

>> but the actual link seems to be generated correctly
> It's not
Oh, you're right, I just mean it's an actual URL, not like how Dokka HTML has partial links that are re-computed later.

[CLOVIS]

You can find the Gradle plugin here and the Dokka plugin here

[CLOVIS]

Correct, currently my plugin never generates partial links (because I rewrote the renderer and didn't write any code allowing that). Link generation happens here.

[CLOVIS]

(to be clear, it probably should generate partial links, but I don't understand how they work nor how to generate them at the moment)

[Adam S]

I'm trying to think why the partial links might be useful here, but I guess you could just generate everything all in one go 🤔

[Adam S]

avoiding partial links would be good for performance, Dokka HTML is slow for many reasons, one being it has to read and parse the HTML to discover and re-write the partial links

[Adam S]

> It currently contains a relative link module/foo.html , which therefore leads to module/module/foo.html .
Ahhh okay, so the module name isn't duplicated. What happens if LocationProvider returns a relative link? "../$actualLink"

[CLOVIS]

That would probably end with a resolvable link, but I think this is hiding the symptoms rather than finding a solution. IMO the problem was that I had to move the module-level file because different modules would conflict with each other. If the aggregation is fixed, they shouldn't need to be moved anymore and I could go back to the default LocationProvider?

[Adam S]

hmmm maybe, but I think there are essentially two approaches:

• The modules are generated in stable, predictable locations. In which case it's safe to make assumptions. So make relative links to the ../$modulePath, or (like I think you're suggesting) create non-clashing module index pages.
• The module locations are dynamic or configurable, so you'd need multi-round processing (like the HTML plugin) to finalise the links.

[Adam S]

in case it helps: if I re-wrote DGP from scratch (again!) I'd avoid per-subproject configuration.

Each subproject should ship the 'raw materials' (source code, classpath, targets). The aggregating project would collect the files from each subproject and run all Dokka generation steps in a single Gradle Task.

I think it'd be better for performance (no need for multiple Gradle Workers), and the configuration would be easier because it's in one place (at the moment it's per-subproject, which is annoying for things like styling or setting a consistent footer), and determining cross-project links could be done in one step (so it would be easier to compute the cross module links).

[CLOVIS]

I don't intend to make locations configurable on disk, because they could already be reconfigured on MkDocs' side. My goal is to have the structure:

api/
    index.md  # all-modules-page
    <module1>/
       index.md  # module-level page
       <package1>/
           index.md  # package-level page
           A.md  # class A
       <package2>/
           …
    <module2>/
        …