Is it possible to have dokka group certain package...

# dokka

[Jane Lee]

Is it possible to have dokka group certain packages together in any way? I.e if a lot of packages have the same prefix, or by folder name?

[Jane Lee]

Or alternatively does anyone have a workaround to organise things in a better view?

[Oleg Yukhnevich]

Theoretically, yes, by creating a Dokka plugin for this.
You can write you own DocumentableTransformer which can group/ungroup packages inside module and then inject it via CoreExtensions.documentableTransformer in Dokka plugin
Though, not sure, how hard it will be to implement something like this.

It will be also good if you will create an issue in Dokka (https://github.com/Kotlin/dokka/issues/new/choose) with your use case (and example if possible) to understand if it's feasible/possible to simplify such setup

[Jane Lee]

Thank you, I'll investigate that and create an issue today too.

[Jane Lee]

@Oleg Yukhnevich I just have one more question please.
Ultimately what i'm trying to achieve is something that has a bit more structure and organization to the navigation section. I have a repo with many folders I need to document and i do not want everything to show as one big list of package names on the left hand side. If you notice below Data has some files and then Presentation has some more files (which I'm assuming are just folders within a project). This however was just an image I found online. I'm using the dokka CLI also. Is this possible using the CLI?

[Jane Lee]

As far as I can tell, the above was generated using DokkaTaskPartial and DokkaMultiModuleTask but I have no actual visibility in how it was implemented

[Oleg Yukhnevich]

Overall, it's possible with CLI, you will just need to build this plugin to jar and path to CLI (via pluginsClasspath as any other plugin) - https://kotlinlang.org/docs/dokka-cli.html
Im not sure, that Im following on what do you want to achieve 😞
Can you please provide an example on what do you want in the end?
F.e. I do want my navigation panel to look like this:

- Data
- Presentation
  - com.devbase.presentation
  - com.devbase.presentation.base
  - ...
  - com.devbase.presentation.recyclerview
    - DevItemViewHolder
    - DevRecyclerViewAdapter
  - com.devbase.presentation.recyclerview.endless
  - ...

[Jane Lee]

Apologies I could have explained better 😊 I have a multi module project and I would like for these top level folders (each module) to represent the menu items displayed in the navigation, so something like below where Data, Presentation and AnotherTopLevelFolder are all folders in my root project

- Data
  - com.mypackage.main
  - com.anotherpackage.base
- Presentation
  - com.devbase.presentation
  - com.devbase.presentation.base
  - ...
  - com.devbase.presentation.recyclerview
    - DevItemViewHolder
    - DevRecyclerViewAdapter
  - com.devbase.presentation.recyclerview.endless
- AnotherTopLevelFolder
  - com.morepackages.base

I can use the CLI right now to reference multiple top level folders and render the documentation with the packages inside those folders but I end up with one long navigation that has all of the packages in a list and this is very hard to navigate and read, so i'm trying to organize the packages based on their top level folders.
Thank you again for the help - much appreciated!

[Jane Lee]

For reference, what I have now in the left hand navigation is something like:

- Root
  - com.mypackage.main
  - com.anotherpackage.base
  - com.devbase.presentation
  - com.devbase.presentation.base
  - com.devbase.presentation.recyclerview
  - com.devbase.presentation.recyclerview.endless
  - com.morepackages.base

[Oleg Yukhnevich]

Still not sure, that Im following regarding what is the issue 🙂
Here is for example default layout for multi module project: https://whyoleg.github.io/cryptography-kotlin/api/ (screenshot attached)
And it looks the same as in your example

What you have now, is like a combined result from all sources
BTW, why are you using CLI?

[Jane Lee]

Yep that's the structure I'm looking for 😊 I'm able to achieve it with gradle but my project cannot use gradle/maven and needs to use the CLI (we are using Bazel). I guess my question is around the set up needed to achieve this structure when using the CLI as when I am adding multiple source sets it seems to render all packages in a list like below:

- Root
  - com.mypackage.main
  - com.anotherpackage.base
  - com.devbase.presentation
  - com.devbase.presentation.base
  - com.devbase.presentation.recyclerview
  - com.devbase.presentation.recyclerview.endless
  - com.morepackages.base

java -jar dokka-cli-1.9.10.jar \
-pluginsClasspath "./dokka-base-1.9.10.jar;./analysis-kotlin-descriptors-1.9.10.jar;./kotlinx-html-jvm-0.8.0.jar;./freemarker-2.3.31.jar" \
-sourceSet "-src /Users/jane/Projects/dokka-test/Data -src /Users/jane/Projects/dokka-test/Presentation"\
-outputDir "./documentation/dokka/html"

[Oleg Yukhnevich]

Okay, now I understand, you just need to know how to build multi-module project via CLI.
1. Im not sure, that required options are available in CLI now, so you will need to pass configuration as json (https://kotlinlang.org/docs/dokka-cli.html#run-with-json-configuration)
2. the workflow is that first you will need to run dokka cli over each project/module and then run dokka one more time with aggregated results
3. I will attach 2 JSON configurations from my project (cryptography-kotlin), I've omitted some details regarding multiplatform, so may be you will need to add/remove/changes some values there.
4. When running dokka for projects you will need to set delayTemplateSubstitution=true in json (example in core.json)
5. When running dokka for aggregation you will need to provide an array modules with names/paths to outputs of dokka execution results from previous steps ; delayTemplateSubstitution=false (example in multimodule.json)
Hope this helps! feel free to ask additional questions, I will try to help 🙂

multimodule.jsoncore.json

[Jane Lee]

Thank you thats very helpful I appreciate it! 😊 I didn't see any references to the above in any of the docs, do you know if this side of things documented anywhere by any chance? I did some set up but I'm getting 'nothing to document' so just trying to debug and see if there's anything that would help me understand what multiplatform changes I might need to configure further.

For reference my multimodule file is looking like this:

{
  "moduleName": "dokka-test",
  "moduleVersion": "0.1",
  "outputDir": "/Users/jane/Projects/dokka-test/documentation",
  "pluginsClasspath": [
    "./dokka-base-1.9.10.jar",
    "./kotlinx-html-jvm-0.8.0.jar",
    "./analysis-kotlin-descriptors-1.9.10.jar",
    "./freemarker-2.3.31.jar"
  ],
  "pluginsConfiguration": [],
  "modules": [
    {
      "name": "data",
      "relativePathToOutputDirectory": "data",
      "includes": [
        "/Users/jane/Projects/dokka-test/data/README.md"
      ],
      "sourceOutputDirectory": "/Users/jane/Projects/dokka-test/data/build/dokka/htmlPartial"
    },
    {
      "name": "presentation",
      "relativePathToOutputDirectory": "presentation",
      "includes": [
        "/Users/jane/Projects/dokka-test/presentation/parentProjectA/ModuleA.md"
      ],
      "sourceOutputDirectory": "/Users/jane/Projects/dokka-test/presentation/build/dokka/htmlPartial"
    }
  ],
  "failOnWarning": false,
  "delayTemplateSubstitution": false,
  "suppressObviousFunctions": true,
  "suppressInheritedMembers": false,
  "finalizeCoroutines": true
}

where data and presentation are folders at the root of my project

[Oleg Yukhnevich]

I didn't see any references to the above in any of the docs

Sad, but no, there is no documentation for building multi-module documentation via CLI 😞

Regarding your issue - totally forgot - you need also to add dokka all-modules-page-plugin (which enabled multi-module behaviour) and templating-plugin jars when running aggregate task

[Oleg Yukhnevich]

You can also take a look here: https://github.com/Kotlin/dokka/issues/2770#issuecomment-1347673833 may be this will also help

[Jane Lee]

Thank you so much 🙂 I feel like I'm almost there but the navigation does not seem to be generating correctly. I've added a repo here to demonstrate what I'm doing and what's being generated. Is there something else I'm missing with regard to the navigation? This test was more of a POC targeting 2 modules for doc generation using the source and apps json files.
Thank you again for the support I really appreciate it 😊

[Oleg Yukhnevich]

I've checked your project locally, big thanks for the reproducer!
Looks like in multimodule.json in modules array, field name is case-sensitive 🙂
Now you modules have names Source and Apps (in apps/source json), but in multimodule.json you use source and apps
I've changed them to be the same and everything works now!

[Jane Lee]

Nice 🥳 thanks for taking a look. I just have a couple of questions on the functionality and then I think I’m done.
1. Is it possible to generate a format other than html using the CLI?
2. Is it also possible to have another navigation item sitting between the module name and packages in the left hand side navigation to provide further organization? For example:

- Data
- Source
 - AnotherFolder
  - demo
 - OneMoreFolder
  - main

Where Source has 2 folders within it, AnotherFolder and OneMoreFolder

Thanks again for your help 😊

[Oleg Yukhnevich]

nice! glad I helped!
1. yes, it's possible, you need to just add jar with plugin to pluginClasspath (but not sure, that every format will work fine with multi-module setup) What format do you want? And out of curiosity, why do you need other format? 🙂
2. not right now. now it's possible only to have module-package-[class]-declarations (class is optional, as there are top-level declarations). But feel free to create in issue on GitHub, with use-case why do you need this feature

[Jane Lee]

What format do you want? And out of curiosity, why do you need other format? 🙂

I was more wondering about markdown as an alternative format, we have a use case to include some previously generated markdown files in the documentation that will explain some other parts of the system

1. not right now. now it's possible only to have module-package-[class]-declarations (class is optional, as there are top-level declarations). But feel free to create in issue on GitHub, with use-case why do you need this feature
Thanks, I’ll get this submitted

Thanks again for your help really appreciate it 😊

[Jane Lee]

@Oleg Yukhnevich Sorry, me again 🙂
I've been trying to get around this error for my multimodule config when using the gfm plugin with the all-modules plugin but there seems to be a conflict. Is there a way around this by any chance? Couldn't find any references in the docs or slack history unfortunately.

Exception in thread "main" java.lang.IllegalStateException: Conflicting overrides: [Extension: org.jetbrains.dokka.allModulesPage.AllModulesPagePlugin/multimoduleLocationProvider, Extension: org.jetbrains.dokka.gfm.GfmPlugin/locationProvider]

"pluginsClasspath": [
  "./dokka/dependencies/dokka-base-1.9.10.jar",
  "./dokka/dependencies/analysis-kotlin-descriptors-1.9.10.jar",
  "./dokka/dependencies/freemarker-2.3.31.jar",
  "./dokka/dependencies/all-modules-page-plugin-1.9.10.jar",
  "./dokka/dependencies/templating-plugin-1.9.10.jar",
  "./dokka/dependencies/gfm-plugin-1.9.10.jar"
],

As always appreciate the help 😄

[Jane Lee]

Also, fwiw I can render via the cli using the below but that doesn't seem to render the navigation

java -jar ./dokka/dependencies/dokka-cli-1.9.10.jar \
     -pluginsClasspath "./dokka/dependencies/dokka-base-1.9.10.jar;./dokka/dependencies/analysis-kotlin-descriptors-1.9.10.jar;./dokka/dependencies/kotlinx-html-jvm-0.8.0.jar;./dokka/dependencies/freemarker-2.3.31.jar;./dokka/dependencies/gfm-plugin-1.9.10.jar;" \
     -sourceSet "-src /Users/jane/Projects/dokka-test/apps/demo/diagrams -src /Users/jane/Projects/dokka-test/apps/demo/linking" \
     -outputDir "/Users/jane/Projects/dokka-test/dokka/build/docs"

But cannot use the json approach java -jar ./dokka/dependencies/dokka-cli-1.9.10.jar ./dokka/config/multimodule.json

[Oleg Yukhnevich]

Sorry for the delay, I somehow missed your messages...
So, regarding GFM, I've rechecked Gradle setup: you need to additionally add gfm-template-processing-plugin when generating multi-module documentation with GFM

[Oleg Yukhnevich]

via just CLI arguments you will not be able to build multi-module, as there is no argument there to provide information of previously built modules

[Jane Lee]

No problem at all - thank you so much for the help! Just 1 more thing, I noticed when I try to include a readme.md file in the multimodule config it doesn't seem to render it for the module and i'm wondering is there maybe another plugin i'm missing? I have # Module name_of_module at the top of each readme and that matches the name of the source set mentioned (and case sensitive). I did however notice that the first line of the readme is displayed in the 'all-modules' screen but when clicking into the package itself the rest of the readme isn't shown. Would you have any idea what I'm missing here? This is the last thing i'm looking to solve so almost there 😄 Thanks again for the help with everything

[Jane Lee]

multimodule.json

{
  "moduleName": "App",
  "moduleVersion": "0.1",
  "outputDir": "/Users/jane/Projects/dokka-test/docs",
  "pluginsClasspath": [
    "./dokka/dependencies/dokka-base-1.9.10.jar",
    "./dokka/dependencies/analysis-kotlin-descriptors-1.9.10.jar",
    "./dokka/dependencies/freemarker-2.3.31.jar",
    "./dokka/dependencies/all-modules-page-plugin-1.9.10.jar",
    "./dokka/dependencies/templating-plugin-1.9.10.jar",
    "./dokka/dependencies/annotations-24.1.0.jar",
    "./dokka/dependencies/kotlin-stdlib-1.9.22.jar",
    "./dokka/dependencies/gfm-template-processing-plugin-1.9.10.jar",
    "./dokka/dependencies/gfm-plugin-1.9.10.jar",
    "./dokka/dependencies/kotlin-stdlib-common-1.9.22.jar",
    "./dokka/dependencies/kotlinx-html-jvm-0.8.0.jar"
  ],
  "pluginsConfiguration": [],
  "modules": [
    {
      "name": "demo-diagrams",
      "relativePathToOutputDirectory": "apps/demo/diagrams",
      "includes": [
        "/Users/jane/Projects/dokka-test/apps/demo/diagrams/README.md"
      ],
      "sourceOutputDirectory": "/Users/jane/Projects/dokka-test/dokka/build/docs/diagrams"
    },
    {
      "name": "Extensions",
      "relativePathToOutputDirectory": "apps/demo/extensions",
      "includes": [],
      "sourceOutputDirectory": "/Users/jane/Projects/dokka-test/dokka/build/docs/extensions"
    },
    {
      "name": "linking",
      "relativePathToOutputDirectory": "apps/demo/linking",
      "includes": [
        "/Users/jane/Projects/dokka-test/apps/demo/linking/README.md"
      ],
      "sourceOutputDirectory": "/Users/jane/Projects/dokka-test/dokka/build/docs/linking"
    }
  ],
  "failOnWarning": false,
  "delayTemplateSubstitution": false,
  "suppressObviousFunctions": true,
  "includes": [],
  "suppressInheritedMembers": false,
  "finalizeCoroutines": true
}

[Oleg Yukhnevich]

I did however notice that the first line of the readme is displayed in the 'all-modules' screen but when clicking into the package itself the rest of the readme isn't shown.

This means, that includes which are passed into multimodule.json are resolved correctly (and you see first line), but includes are not resolved on side of the modules.
So in multi-module case you will need to provide same files in includes in both multimodule.json and in projects configurations. For projects it should be in sourceSets.[i].includes (example here: https://kotlinlang.org/docs/dokka-cli.html#source-set-configuration)

[Jane Lee]

I see, if I add the includes statement to the project sourceSets it triggers the error Exception in thread "main" java.lang.IllegalStateException: Unexpected classifier: "#", expected either "Module" or "Package". though and adding it to the end of the file does not include it in the generated docs 🤔

For reference:
(no errors but not showing)

{
  "moduleName": "linking",
  "moduleVersion": "0.1",
  "outputDir": "/Users/jane/Projects/dokka-test/dokka/build/docs/linking",
  "sourceSets": [
    {
      "displayName": "linking",
      "sourceSetID": {
        "scopeId": ":linking:dokkaHtmlPartial",
        "sourceSetName": "linking"
      },
      "classpath": [],
      "sourceRoots": [
        "/Users/jane/Projects/dokka-test/apps/demo/linking"
      ],
      "samples": [
        "/Users/jane/Projects/dokka-test/apps/samples"
      ],
      "includeNonPublic": false,
      "reportUndocumented": false,
      "skipEmptyPackages": true,
      "skipDeprecated": false,
      "jdkVersion": 8,
      "languageVersion": null,
      "apiVersion": null,
      "noStdlibLink": false,
      "noJdkLink": false,
      "suppressedFiles": [],
      "analysisPlatform": "jvm",
      "documentedVisibilities": [
        "PUBLIC"
      ]
    }
  ],
  "pluginsClasspath": [
    "./dokka/dependencies/dokka-base-1.9.10.jar",
    "./dokka/dependencies/kotlinx-html-jvm-0.8.0.jar",
    "./dokka/dependencies/suppress-undocumented-dokka-plugin-1.1.jar",
    "./dokka/dependencies/analysis-kotlin-descriptors-1.9.10.jar",
    "./dokka/dependencies/freemarker-2.3.31.jar",
    "./dokka/dependencies/html-mermaid-dokka-plugin-0.4.6-javadoc.jar"
  ],
  "pluginsConfiguration": [],
  "modules": [],
  "failOnWarning": true,
  "delayTemplateSubstitution": true,
  "suppressObviousFunctions": true,
  "suppressInheritedMembers": true,
  "finalizeCoroutines": true,
  "includes": ["README.md"] -> tried absolute path here too 
}

(error described above)

{
  "moduleName": "linking",
  "moduleVersion": "0.1",
  "outputDir": "/Users/jane/Projects/dokka-test/dokka/build/docs/linking",
  "sourceSets": [
    {
      "displayName": "linking",
      "sourceSetID": {
        "scopeId": ":linking:dokkaHtmlPartial",
        "sourceSetName": "linking"
      },
      "classpath": [],
      "sourceRoots": [
        "/Users/jane/Projects/dokka-test/apps/demo/linking"
      ],
      "samples": [
        "/Users/jane/Projects/dokka-test/apps/samples"
      ],
      "includes": ["README.md"],
      "includeNonPublic": false,
      "reportUndocumented": false,
      "skipEmptyPackages": true,
      "skipDeprecated": false,
      "jdkVersion": 8,
      "languageVersion": null,
      "apiVersion": null,
      "noStdlibLink": false,
      "noJdkLink": false,
      "suppressedFiles": [],
      "analysisPlatform": "jvm",
      "documentedVisibilities": [
        "PUBLIC"
      ]
    }
  ],
  "pluginsClasspath": [
    "./dokka/dependencies/dokka-base-1.9.10.jar",
    "./dokka/dependencies/kotlinx-html-jvm-0.8.0.jar",
    "./dokka/dependencies/suppress-undocumented-dokka-plugin-1.1.jar",
    "./dokka/dependencies/analysis-kotlin-descriptors-1.9.10.jar",
    "./dokka/dependencies/freemarker-2.3.31.jar",
    "./dokka/dependencies/html-mermaid-dokka-plugin-0.4.6-javadoc.jar"
  ],
  "pluginsConfiguration": [],
  "modules": [],
  "failOnWarning": true,
  "delayTemplateSubstitution": true,
  "suppressObviousFunctions": true,
  "suppressInheritedMembers": true,
  "finalizeCoroutines": true,
  "includes": ["README.md"] -> tried absolute path here too 
}

[Oleg Yukhnevich]

"includes": ["README.md"] in root of the json doesn't work and will be silently ignored as it's used only for multi-module case as a root page
So you need to put it inside sourceSet.
Could you share README.md (at least it structure)?
You can take a look on the structure which is supported: https://kotlinlang.org/docs/dokka-module-and-package-docs.html
so here you will need to have something like:

# Module linking

here goes docs

And as you have first paragraphs in multi-module, that means, that it's recognized there, could you try to provide the same file for project generation :

"includes": ["/Users/jane/Projects/dokka-test/apps/demo/linking/README.md"]

[Jane Lee]

I actually took the readme from your project here in an attempt to step through possible issues 😊 The issue i'm having is no matter what readme I try to embed in the sourceSet I get this error Exception in thread "main" java.lang.IllegalStateException: Unexpected classifier: "#", expected either "Module" or "Package". so the only place I can embed it is in the root of the json. It doesn't matter whether I use just the filename or the absolute path. So this structure does not work due to the error:

{
  "moduleName": "linking",
  "moduleVersion": "0.1",
  "outputDir": "/Users/jane/Projects/dokka-test/dokka/build/docs/linking",
  "sourceSets": [
    {
      "displayName": "linking",
      "sourceSetID": {
        "scopeId": ":linking:dokkaHtmlPartial",
        "sourceSetName": "linking"
      },
      "classpath": [],
      "sourceRoots": [
        "/Users/jane/Projects/dokka-test/apps/demo/linking"
      ],
      "samples": [
        "/Users/jane/Projects/dokka-test/apps/samples"
      ],
      "includes": ["/Users/jane/Projects/dokka-test/apps/demo/linking/README.md"],
      "includeNonPublic": false,
      "reportUndocumented": false,
      "skipEmptyPackages": true,
      "skipDeprecated": false,
      "jdkVersion": 8,
      "languageVersion": null,
      "apiVersion": null,
      "noStdlibLink": false,
      "noJdkLink": false,
      "suppressedFiles": [],
      "analysisPlatform": "jvm",
      "documentedVisibilities": [
        "PUBLIC"
      ]
    }
  ],
  "pluginsClasspath": [
    "./dokka/dependencies/dokka-base-1.9.10.jar",
    "./dokka/dependencies/kotlinx-html-jvm-0.8.0.jar",
    "./dokka/dependencies/suppress-undocumented-dokka-plugin-1.1.jar",
    "./dokka/dependencies/analysis-kotlin-descriptors-1.9.10.jar",
    "./dokka/dependencies/freemarker-2.3.31.jar",
    "./dokka/dependencies/html-mermaid-dokka-plugin-0.4.6-javadoc.jar"
  ],
  "pluginsConfiguration": [],
  "modules": [],
  "failOnWarning": true,
  "delayTemplateSubstitution": true,
  "suppressObviousFunctions": true,
  "suppressInheritedMembers": true,
  "finalizeCoroutines": true,
}

[Jane Lee]

Ah, I manually typed in "includes" : [] and it seems to be picking it up properly now 🤷‍♀️ Either way it looks good to go - thank you again for all of the help 😄

[Oleg Yukhnevich]

Cool! Glad that everything is working now, it was a hard path...

[Jane Lee]

Hopefully this thread can help someone else too in the future 😄 thank you again

[Jane Lee]

@Oleg Yukhnevich Sorry to bother you again but I have 1 more question if thats okay 🙂 Is it possible to use relative paths for the module sourceRoots and multimodule outputDir using the approach we discussed above? I see there's support for relative paths In certain scenarios but I'm hoping to be able to use it for all module generation so each member of the team doesn't have to manually change/specify this on their end

[Oleg Yukhnevich]

Hey!
Yeah, relative paths should work fine
But please use recently released Dokka 1.9.20, as it contains a fix for sourceRoots