Generate an API reference
Render a resource's KDoc with Dokka, and ship the apidocs zip a consumer reads.
A resource reaches a consumer as an installed tree. The consumer declares catiaMagic("...@zip"),
Forge unpacks the archive into dev-env/, and their build compiles against the jars in that
directory. The compiler discards KDoc, the archive carries no Maven module, and a compileOnly file
tree resolves no -javadoc.jar, so nothing on that path carries your documentation. What a consumer
can read is what Dokka rendered.
Forge renders it and packages it for you. This page covers what you get, what you may override, and how the archive reaches the person who needs it.
You declare nothing
Forge applies org.jetbrains.dokka to a project that carries Kotlin sources, and assemble writes
the render to build/distributions/<resource-archive-name>-apidocs.zip.
A plugins block naming id("org.jetbrains.dokka") with a version fails to resolve, because
Forge's own dependency already puts the plugin on your buildscript classpath. Remove the line:
plugins {
id("com.mbseconsulting.forge") version "9.0.0"
// id("org.jetbrains.dokka") version "2.2.0" ← delete this
}A resource holding profiles and templates alone gets neither the plugin nor the archive. Forge tests
for a .kt file under src/main/kotlin or src/test/kotlin before applying anything, so a
model-only resource pays nothing and ./gradlew zipApiDocs there reports SKIPPED.
The two defaults Forge sets
| Setting | Value | Why |
|---|---|---|
documentedVisibilities | Public, Protected | A profile binding extends StereotypeReference and calls its protected tag factories. A reference documenting public members alone omits the factories a binding author calls. |
reportUndocumented | true | Names every public declaration that would render with an empty description. Dokka emits a warning, so a gap reports without failing the build. |
reportUndocumented is why a first build after upgrading prints warnings naming your own
declarations. Each one is a public symbol a consumer can call and cannot read about. The build stays
green.
Override a default
Write your own dokka { } block. It runs after Forge's and wins:
dokka {
dokkaSourceSets.configureEach {
// Forge sets Public + Protected; narrow it back if a resource has no bindings.
documentedVisibilities.set(setOf(VisibilityModifier.Public))
}
}The import is org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier. You need no
dependency declaration for it — Forge already supplies the plugin.
Turn the slice off
com.mbseconsulting.forge.configure.dokka=falseForge then applies no Dokka plugin of its own, and zipApiDocs reports SKIPPED — including for a
project that applies id("org.jetbrains.dokka") itself, because the flag governs the task rather
than only the plugin apply. See Properties.
Build cost
The render runs on the first build after a change to your sources, your KDoc, or the compile
classpath. An unchanged rebuild finds dokkaGeneratePublicationHtml and zipApiDocs UP-TO-DATE
and renders nothing, so the cost falls on the builds that changed something.
Delivering the archive
Sending it stays your act. The archive reaches no Maven repository, on the rule
Package the project sources states for zipSources: publication reads
publication-index.json, and zipApiDocs writes no entry there. The index sits in
build/publication/, outside the release set; see Build outputs.
build/distributions/
acme-profile-1.4.0-2024x.zip
com.acme.profile-1.4.0-2024x.zip
acme-profile-1.4.0-2024x-sources.zip
acme-profile-1.4.0-2024x-apidocs.zip ← this page
acme-profile-1.4.0-2024x-report.html
acme-profile-1.4.0-2024x-report.jsonHanding that folder over hands over the reference, so removing the archive is the deliberate act.
The base name comes from com.mbseconsulting.forge.resource.name and
com.mbseconsulting.forge.resource.humanVersion, the same two keys that name the resource zip.
Missing either, zipApiDocs fails naming the key rather than writing a delivery under an invented
name.
Your project still declares its repositories
Dokka resolves dokka-base, templating-plugin, analysis-kotlin-symbols and analysis-markdown
from your repositories when the render runs, so mavenCentral() has to be there. Forge adds the
CATIA Magic repositories and nothing else; see
Configure code quality,
which covers the same requirement for Spotless.
Related pages
| Need | Read |
|---|---|
| Every property key and its rule | Properties |
zipApiDocs and its lifecycle edge | Tasks |
| Spotless, JaCoCo and ProGuard | Configure code quality |
| Packaging the sources beside it | Package the project sources |
| Writing the KDoc this renders | the conventions:documenting-code skill |