Possible to generate multi module projects using the CLI?

[rohan-mehta]

Question
I'm following the Command Line guide to create docs. The docs are a bit out of date, but I was able to get it working. However, I'm not totally sure how I might use it to generate multi module docs. Are there any examples I can follow?

Installation

• Operating system: macOS
• Build tool: CLI
• Dokka version: 1.7.20

[rohan-mehta]

Things I tried that didn't work:

1. Specifying both sourceSets + modules in the JSON config. Result was that modules was just ignores
2. Running the CLI tool multiple times, first two times with different sourceSets and then after with modules but no sourceSets. Result was two different websites generated, third step did nothing.

I also read the CLI runner code. As far as I can tell, the code just doesn't take into account multi module. That said, I'm new to the project so I may have missed something. Please let me know if there is in fact a way to do what I want :)

[IgnatBeresnev]

It should be possible, although not quite straightforward and easy. Frankly I've neither done it, nor heard of anyone succeeding, nor would I recommend doing it 😅

Is there any reason you want to use the CLI runner for this as opposed to using the Gradle plugin? Maybe we could spend less time on resolving the blocker?

---

If you're determined to use the CLI runner, here's my thoughts:

We've re-written documentation in #2728, it's not out yet, but you can see the preview for the CLI runner here, it should help you with configuration and understanding of what's going out. Note that some configuration properties I'm going to mention are not covered in the documentation as this use case should be quite rare.

You can read how *MultiModule and *Partial tasks work for the Gradle plugin here. You'll have to do something similar, but manually.

First, Partial tasks are run for each module separately, and then the parent MultiModule task is run, which processes outputs from all partial tasks and produces ready-to-use documentation. Partial tasks are run with DokkaConfiguration#delayTemplateSubstitution set to true - this leaves template resolution to the MultiModule task so that cross-module references, navigation links and everything else can be linked correctly (since it knows about all modules).

So it looks like you'd have to have separate JSON configurations for each module (with delayTemplateSubstitution), similar to how DokkaTaskPartial is created for each subproject.

Then you'd need a separate JSON configuration for the MultiModule run. You'd probably have to supply templating-plugin and all-module-page-plugin to pluginsClasspath, and maybe some additional libraries, you'll figure it out by resolving ClassNotFound errors :) The plugins should get bootstrapped automatically.

For the MultiModule run only, it looks like you'll have to configure DokkConfiguration#module property and provide locations of the modules.

CLI runner's JSON configuration is deserialized as DokkaConfiguration, so the mapping of fields is 1:1, it should be easy enough to understand which names and values to set.

With all of that done, it should either work as expected or you should be close.

You can look at the Gradle plugin, its tasks and configuration for examples, although that's also not as easy to extract information from it. You can use DokkaConfiguration.toJsonString() extension to dump existing configuration as JSON, but there's no way to get configuration of a task from the buildscript, so you'll have to stop in debugger to use it, probably somewhere in SingleModuleGeneration or AllModulesPageGeneration (they have access to configuration through context.configuration). But that could be the easiest solution, actually - add the gradle plugin to your project, let it auto-configure all tasks (and thus configurations), and then just dump configurations as JSONs that you'll be able to use from the CLI runner.

[rohan-mehta]

Thanks for the reply @IgnatBeresnev. Your suggestion worked. The one slight gotcha for me, was that the MultiModule run silently did nothing if I didn't pass the templating-plugin and all-module-page-plugin. Once I passed those, it successfully generated things correctly. Thanks a ton for helping me so quickly!

[IgnatBeresnev]

I'm glad it worked 👍

Could you please describe your use case for the CLI runner? Why not use the Gradle plugin?

We'd like to know more why people use it so that we can either improve the CLI runner itself or resolve problems in the Gradle plugin that stop people from using it.

[rohan-mehta]

Oh, my project doesn’t use gradle as the build system. The CLI runner is really useful if you have a different build system eg CMake, bazel, buck, so would be great if you kept investing in it :)