Hello! I'm configuring dokka currently and wanted to include the changelog file in my generated HTM...

# dokka

[Sebastien Leclerc Lavallee]

Hello!

I'm configuring dokka currently and wanted to include the changelog file in my generated HTML
I have this at the root build.gradle.kts :

subprojects {
  apply("com.dokka...")

  afterEvaluate {
    dokka {
     dokkaPublications.html {
      moduleName.set("SOME - " + project.name)
      includes.from(project.layout.projectDirectory.file("CHANGELOG.md"))
     }
    }
  }
}

The file is at the correct location for each subproject, but I don't see my changelog file when I execute
./gradlew dokkaGenerate

Is there anything missing ?
Is that something that's possible?

Thanks! 🙂

[jw]

project. is referencing the root, not the subproject

[Sebastien Leclerc Lavallee]

But the project.name resolve to the correct submodule name and if I println the path, it’s correct

[jw]

Not sure then

[jw]

Maybe afterevaluate is too late to mutate?

[jw]

Why even have that block? The plugin extension is made available synchronously

[Sebastien Leclerc Lavallee]

Yeah I had move to inside afterEvaluate because I wanted to have the project version which isn't available there because I read it from a file.

I tried both

includes.from(project.layout.projectDirectory.file("CHANGELOG.md"))
// or
includes.from("CHANGELOG.md")

but neither worked.

Do you know where / how it should show?

[Adam Semenenko]

Does each subproject have a CHANGELOG.md, or is there a single CHANGELOG.md in the root project?

[Adam Semenenko]

because I wanted to have the project version which isn't available there

Could you show how you want to use the project version? You could probably just wrap it in a provider to make it lazy, e.g. provider { project.version.toString() }

afterEvaluate {} is really delicate, so try to avoid it! Even if you have to use it, try to limit it as much as possible - don't put the whole dokka {} block in there, only the part that should be lazy.

[Sebastien Leclerc Lavallee]

@Adam Semenenko They each all have a changelog file

I did move the dokka block out of afterEvaluate { } but still no MD file showing

[Adam Semenenko]

How are the changelog files formatted?

The markdown files added to includes have to have a very specific format for Dokka to recognise them, just adding regular markdown files will be ignored.

https://github.com/Kotlin/dokka/blob/2ed83e5811057623ec16c36c66435fa300d3c9ca/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaPublication.kt#L130-L134

[Sebastien Leclerc Lavallee]

In the example, I see only 2 first level header (#), does that mean it works only with first level headers?

[Adam Semenenko]

the format is specified in more detail here: https://kotlinlang.org/docs/dokka-module-and-package-docs.html#file-format

[Adam Semenenko]

just try putting # Module <name-of-module> at the start of the changelog (replacing <name-of-module> with the actual Dokka module name)

[Sebastien Leclerc Lavallee]

Ha yes! I do have lists in my file. I'll try with less stuff in it

[Adam Semenenko]

nice!

[Sebastien Leclerc Lavallee]

I did try with a very simple file, on a 2-3 headers and some texts and nothing showed in the output. Should I see something in the index.html ?

[Adam Semenenko]

if you have a module.md file that's added to Dokka via includes(), and the module.md is formatted correctly, then yes, you should see something in index.html

[Sebastien Leclerc Lavallee]

Each module has it's own THING.md file

subprojects {
  dokka {
   dokkaPublications.html {
     moduleName.set("CBCRC - " + project.name)
     includes.from("THING.md")
   }
 }
}

And then ./gradle dokkaGenerate generated the site structure, but no sigh of the markdown file content

[Adam Semenenko]

sorry, that's frustrating. I'm not sure what the problem could be. Is there any information in the dokka log? It should be buried in the build/tmp/ dir somewhere.

[Adam Semenenko]

The strict formatting of the includes bugs me too, it's hard to get right

[Adam Semenenko]

could you share the exact content of one of the `THING.md`s?

[Sebastien Leclerc Lavallee]

# Things

This and that

## Others

Stuff!

[Adam Semenenko]

It has to be like this:

# Module CBCRC project.name

This and that

## Others

Stuff!

[Adam Semenenko]

replace project.name with the actual project name

[Sebastien Leclerc Lavallee]

OH

Like exactly the same name as the module name I set
Ok ok I didn't understood that 😅

[Sebastien Leclerc Lavallee]

I'll give it a try

[Sebastien Leclerc Lavallee]

Thanks for the help! I did try to change the top level header with Module <modulename> but it did not fix my issue.
I'll put that aside for now. And get back to it later. Maybe try another way of applying this plugin (not inside subproject { } )