Forge
How-to guides

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

SettingValueWhy
documentedVisibilitiesPublic, ProtectedA profile binding extends StereotypeReference and calls its protected tag factories. A reference documenting public members alone omits the factories a binding author calls.
reportUndocumentedtrueNames 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=false

Forge 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.json

Handing 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.

NeedRead
Every property key and its ruleProperties
zipApiDocs and its lifecycle edgeTasks
Spotless, JaCoCo and ProGuardConfigure code quality
Packaging the sources beside itPackage the project sources
Writing the KDoc this rendersthe conventions:documenting-code skill

On this page