Gradle과 Dokka

Gradle과 Dokka (Gradle)

NOTE: 이 가이드는 Dokka Gradle 플러그인(DGP) v2 모드에 적용돼요. 이전 DGP v1 모드는 더 이상 지원되지 않아요. v1에서 v2 모드로 업그레이드한다면 Migration 가이드를 참고하세요.

Gradle 기반 프로젝트의 문서를 생성하려면 Dokka용 Gradle 플러그인을 사용할 수 있어요.

Dokka Gradle 플러그인(DGP)은 프로젝트에 대한 기본 자동 구성을 제공하고, 문서를 생성하는 Gradle 태스크를 포함하며, 출력을 맞춤 설정하는 구성 옵션을 제공해요.

Dokka를 직접 만져 보면서 다양한 프로젝트에 어떻게 구성하는지 살펴보려면 Gradle 예시 프로젝트를 참고하세요.

출처: Gradle

본문

지원 버전 (Supported versions)

프로젝트가 최소 버전 요구 사항을 충족하는지 확인하세요.

요구 사항	최소 버전
Kotlin Gradle 플러그인	1.9 이상

Dokka 적용하기 (Apply Dokka)

Dokka용 Gradle 플러그인을 적용하는 권장 방법은 plugins 블록을 사용하는 거예요. 프로젝트의 build.gradle.kts 파일에 있는 plugins {} 블록에 추가해요.

plugins {
    id("org.jetbrains.dokka") version "2.2.0"
}

plugins {
    id 'org.jetbrains.dokka' version '2.2.0'
}

멀티 프로젝트 빌드를 문서화할 때는, 문서화하려는 모든 하위 프로젝트에 플러그인을 명시적으로 적용해야 해요. Dokka를 각 하위 프로젝트에서 직접 구성하거나, 컨벤션 플러그인으로 하위 프로젝트 전체에 걸쳐 Dokka 구성을 공유할 수 있어요. 자세한 내용은 단일 프로젝트 및 멀티 프로젝트 빌드 구성 방법을 참고하세요.

TIP:

• 내부적으로 Dokka는 Kotlin Gradle 플러그인을 사용해 문서가 생성되는 source set을 자동으로 구성해요. Kotlin Gradle 플러그인을 적용하거나 source set을 수동으로 구성했는지 확인하세요.
• 사전 컴파일된 스크립트 플러그인에서 Dokka를 사용한다면, 제대로 동작하도록 Kotlin Gradle 플러그인을 의존성으로 추가하세요.

빌드 캐시와 구성 캐시 활성화하기 (Enable build cache and configuration cache)

DGP는 Gradle 빌드 캐시와 구성 캐시를 지원해서 빌드 성능을 개선해요.

• 빌드 캐시를 활성화하려면 Gradle 빌드 캐시 문서의 지침을 따르세요.
• 구성 캐시를 활성화하려면 Gradle 구성 캐시 문서의 지침을 따르세요.

문서 생성하기 (Generate documentation)

Dokka Gradle 플러그인에는 HTML과 Javadoc 출력 형식이 내장되어 있어요.

문서를 생성하려면 다음 Gradle 태스크를 사용해요.

./gradlew :dokkaGenerate

dokkaGenerate Gradle 태스크의 핵심 동작은 다음과 같아요.

• 이 태스크는 단일 및 멀티 프로젝트 빌드 모두에 대해 문서를 생성해요.
• 기본적으로 문서 출력 형식은 HTML이에요. 적절한 플러그인을 추가해서 Javadoc 또는 HTML과 Javadoc 두 형식 모두를 생성할 수도 있어요.
• 생성된 문서는 단일 및 멀티 프로젝트 빌드 모두에서 자동으로 build/dokka/html 디렉터리에 놓여요. outputDirectory를 사용해 변경할 수 있어요.

문서 출력 형식 구성하기 (Configure documentation output format)

WARNING: Javadoc 출력 형식은 Alpha 단계예요. 사용하면 버그를 발견하거나 마이그레이션 문제를 겪을 수 있어요. Javadoc을 입력으로 받아들이는 도구들과의 통합 성공은 보장되지 않아요. 책임은 사용자 본인에게 있어요.

API 문서를 HTML, Javadoc 또는 두 형식을 동시에 생성하도록 선택할 수 있어요.

• 프로젝트의 build.gradle.kts 파일에 있는 plugins {} 블록에 해당 플러그인 id를 넣어요.

plugins {
    // Generates HTML documentation
    id("org.jetbrains.dokka") version "2.2.0"

    // Generates Javadoc documentation
    id("org.jetbrains.dokka-javadoc") version "2.2.0"

    // Keeping both plugin IDs generates both formats
}

• 해당 Gradle 태스크를 실행해요.

각 형식에 대응하는 플러그인 id와 Gradle 태스크 목록은 다음과 같아요.

형식	플러그인 id	Gradle 태스크
HTML	id("org.jetbrains.dokka")	./gradlew :dokkaGeneratePublicationHtml
Javadoc	id("org.jetbrains.dokka-javadoc")	./gradlew :dokkaGeneratePublicationJavadoc
(적용된 플러그인 기반 전체 형식)	(위 플러그인들)	./gradlew :dokkaGenerate

TIP:

• dokkaGenerate 태스크는 적용된 플러그인을 기준으로 사용 가능한 모든 형식의 문서를 생성해요. HTML과 Javadoc 플러그인이 모두 적용되어 있다면, dokkaGeneratePublicationHtml 태스크를 실행해 HTML만, 또는 dokkaGeneratePublicationJavadoc 태스크를 실행해 Javadoc만 생성하도록 선택할 수 있어요.

IntelliJ IDEA를 사용한다면 dokkaGenerateHtml Gradle 태스크가 보일 수 있어요. 이 태스크는 단순히 dokkaGeneratePublicationHtml의 별칭이에요. 두 태스크는 완전히 같은 동작을 수행해요.

멀티 프로젝트 빌드에서 문서 출력 집계하기 (Aggregate documentation output in multi-project builds)

Dokka는 여러 하위 프로젝트의 문서를 단일 출력 또는 발행으로 집계할 수 있어요.

문서를 집계하기 전에 모든 문서화 가능한 하위 프로젝트에 Dokka 플러그인을 적용해야 해요.

여러 하위 프로젝트의 문서를 집계하려면 루트 프로젝트의 build.gradle.kts 파일에 dependencies {} 블록을 추가해요.

dependencies {
    dokka(project(":childProjectA:"))
    dokka(project(":childProjectB:"))
}

다음과 같은 구조의 프로젝트가 있다고 해볼게요.

.
└── parentProject/
    ├── childProjectA/
    │   └── demo/
    │       └── ChildProjectAClass.kt
    └── childProjectB/
        └── demo/
            └── ChildProjectBClass.kt

생성된 문서는 다음과 같이 집계돼요.

자세한 내용은 멀티 프로젝트 예시를 참고하세요.

집계된 문서의 디렉터리 (Directory of aggregated documentation)

DGP가 하위 프로젝트를 집계하면, 각 하위 프로젝트는 집계된 문서 안에 자신의 하위 디렉터리를 갖게 돼요. DGP는 전체 프로젝트 구조를 유지해서 각 하위 프로젝트가 고유한 디렉터리를 갖도록 보장해요.

예를 들어 :turbo-lib에 집계가 있고 중첩된 하위 프로젝트 :turbo-lib:maths가 있다면, 생성된 문서는 다음 위치에 놓여요.

turbo-lib/build/dokka/html/turbo-lib/maths/

하위 프로젝트 디렉터리를 직접 지정하면 이 동작을 되돌릴 수 있어요. 각 하위 프로젝트의 build.gradle.kts 파일에 다음 구성을 추가해요.

// /turbo-lib/maths/build.gradle.kts

plugins {
    id("org.jetbrains.dokka")
}

dokka {
    // Overrides the subproject directory
    modulePath.set("maths")
}

이 구성을 적용하면 :turbo-lib:maths 모듈의 생성된 문서가 turbo-lib/build/dokka/html/maths/로 생성되도록 바뀌어요.

javadoc.jar 만들기 (Build javadoc.jar)

라이브러리를 저장소에 게시하려면, 라이브러리의 API 참조 문서가 담긴 javadoc.jar 파일을 제공해야 할 수 있어요.

예를 들어 Maven Central에 게시하려면 프로젝트와 함께 javadoc.jar를 반드시 제공해야 해요. 하지만 모든 저장소에 그런 규칙이 있는 것은 아니에요.

Dokka용 Gradle 플러그인은 이를 기본적으로 지원하는 방법을 제공하지 않지만, 커스텀 Gradle 태스크로 만들 수 있어요. 하나는 HTML 형식으로 문서를 생성하고, 다른 하나는 Javadoc 형식으로 문서를 생성해요.

// To generate documentation in HTML
val dokkaHtmlJar by tasks.registering(Jar::class) {
    description = "A HTML Documentation JAR containing Dokka HTML"
    from(tasks.dokkaGeneratePublicationHtml.flatMap { it.outputDirectory })
    archiveClassifier.set("html-doc")
}

// To generate documentation in Javadoc
val dokkaJavadocJar by tasks.registering(Jar::class) {
    description = "A Javadoc JAR containing Dokka Javadoc"
    from(tasks.dokkaGeneratePublicationJavadoc.flatMap { it.outputDirectory })
    archiveClassifier.set("javadoc")
}

// To generate documentation in HTML
tasks.register('dokkaHtmlJar', Jar) {
    description = 'A HTML Documentation JAR containing Dokka HTML'
    from(tasks.named('dokkaGeneratePublicationHtml').flatMap { it.outputDirectory })
    archiveClassifier.set('html-doc')
}

// To generate documentation in Javadoc
tasks.register('dokkaJavadocJar', Jar) {
    description = 'A Javadoc JAR containing Dokka Javadoc'
    from(tasks.named('dokkaGeneratePublicationJavadoc').flatMap { it.outputDirectory })
    archiveClassifier.set('javadoc')
}

TIP: 라이브러리를 Maven Central에 게시한다면, javadoc.io 같은 서비스를 사용해 별도의 설정 없이 라이브러리의 API 문서를 무료로 호스팅할 수 있어요. 이 서비스는 javadoc.jar에서 직접 문서 페이지를 가져와요. 이 예시에서 볼 수 있듯이 HTML 형식과 잘 작동해요.

구성 예시 (Configuration examples)

가지고 있는 프로젝트 유형에 따라 Dokka를 적용하고 구성하는 방식은 조금씩 달라요. 하지만 구성 옵션 자체는 프로젝트 유형과 관계없이 동일해요.

프로젝트 루트에 build.gradle.kts 또는 build.gradle 파일이 하나 있는 단순하고 평평한 프로젝트라면 단일 프로젝트 구성을 참고하세요.

하위 프로젝트와 여러 개의 중첩된 build.gradle.kts 또는 build.gradle 파일이 있는 더 복잡한 빌드라면 멀티 프로젝트 구성을 참고하세요.

단일 프로젝트 구성 (Single-project configuration)

단일 프로젝트 빌드는 보통 프로젝트 루트에 build.gradle.kts 또는 build.gradle 파일이 하나만 있어요. 단일 플랫폼이거나 멀티플랫폼일 수 있으며, 보통 다음과 같은 구조예요.

단일 플랫폼:

.
├── build.gradle.kts
└── src/
    └── main/
        └── kotlin/
            └── HelloWorld.kt

멀티플랫폼:

.
├── build.gradle.kts
└── src/
    ├── commonMain/
    │   └── kotlin/
    │       └── Common.kt
    ├── jvmMain/
    │   └── kotlin/
    │       └── JvmUtils.kt
    └── nativeMain/
        └── kotlin/
            └── NativeUtils.kt

단일 플랫폼:

.
├── build.gradle
└── src/
    └── main/
        └── kotlin/
            └── HelloWorld.kt

멀티플랫폼:

.
├── build.gradle
└── src/
    ├── commonMain/
    │   └── kotlin/
    │       └── Common.kt
    ├── jvmMain/
    │   └── kotlin/
    │       └── JvmUtils.kt
    └── nativeMain/
        └── kotlin/
            └── NativeUtils.kt

루트 build.gradle.kts 파일에서 Dokka Gradle 플러그인을 적용하고 최상위 dokka {} DSL로 구성해요.

plugins {
    id("org.jetbrains.dokka") version "2.2.0"
}

dokka {
    dokkaPublications.html {
        moduleName.set("MyProject")
        outputDirectory.set(layout.buildDirectory.dir("documentation/html"))
        includes.from("README.md")
   }

    dokkaSourceSets.main {
        sourceLink {
            localDirectory.set(file("src/main/kotlin"))
            remoteUrl.set(URI("https://github.com/your-repo"))
            remoteLineSuffix.set("#L")
        }
    }
}

./build.gradle 안에서:

plugins {
    id 'org.jetbrains.dokka' version '2.2.0'
}

dokka {
    dokkaPublications {
        html {
            moduleName.set("MyProject")
            outputDirectory.set(layout.buildDirectory.dir("documentation/html"))
            includes.from("README.md")
        }
    }

    dokkaSourceSets {
        named("main") {
            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl.set(new URI("https://github.com/your-repo"))
                remoteLineSuffix.set("#L")
            }
        }
    }
}

이 구성은 프로젝트에 Dokka를 적용하고, 문서 출력 디렉터리를 설정하며, 기본 source set을 정의해요. 같은 dokka {} 블록 안에서 커스텀 에셋, 가시성 필터 또는 플러그인 구성을 추가해 더 확장할 수 있어요. 자세한 내용은 구성 옵션을 참고하세요.

멀티 프로젝트 구성 (Multi-project configuration)

멀티 프로젝트 빌드는 보통 여러 개의 중첩된 build.gradle.kts 파일을 포함하며 다음과 비슷한 구조예요.

.
├── build.gradle.kts
├── settings.gradle.kts
├── subproject-A/
│   ├── build.gradle.kts
│   └── src/
│       └── main/
│           └── kotlin/
│               └── HelloFromA.kt
└── subproject-B/
    ├── build.gradle.kts
    └── src/
        └── main/
            └── kotlin/
                └── HelloFromB.kt

.
├── build.gradle
├── settings.gradle
├── subproject-A/
│   ├── build.gradle
│   └── src/
│       └── main/
│           └── kotlin/
│               └── HelloFromA.kt
└── subproject-B/
    ├── build.gradle
    └── src/
        └── main/
            └── kotlin/
                └── HelloFromB.kt

단일 및 멀티 프로젝트 문서는 같은 dokka {}dokka {} DSL을 공유해요.

멀티 프로젝트 빌드에서 Dokka를 구성하는 방법은 두 가지가 있어요.

• 컨벤션 플러그인을 통한 공유 구성(권장): 컨벤션 플러그인을 정의하고 모든 하위 프로젝트에 적용해요. 이렇게 하면 Dokka 설정이 중앙 집중화돼요.
• 수동 구성: 각 하위 프로젝트에 Dokka 플러그인을 적용하고 같은 dokka {} 블록을 반복해요. 컨벤션 플러그인은 필요 없어요.

하위 프로젝트를 구성하고 나면, 여러 하위 프로젝트의 문서를 단일 출력으로 집계할 수 있어요. 자세한 내용은 멀티 프로젝트 빌드에서 문서 출력 집계하기를 참고하세요.

TIP: 멀티 프로젝트 예시는 Dokka GitHub 저장소를 참고하세요.

컨벤션 플러그인을 통한 공유 구성 (Shared configuration via a convention plugin)

컨벤션 플러그인을 설정하고 하위 프로젝트에 적용하는 다음 단계를 따라 해요.

buildSrc 디렉터리 설정하기 (Set up the buildSrc directory)

• 프로젝트 루트에 두 개의 파일이 들어 있는 buildSrc 디렉터리를 만들어요.
• 파일은 settings.gradle.kts와 build.gradle.kts예요.
• buildSrc/settings.gradle.kts 파일에 다음 스니펫을 추가해요.

rootProject.name = "buildSrc"

• buildSrc/build.gradle.kts 파일에 다음 스니펫을 추가해요.

plugins {
    `kotlin-dsl`
}

repositories {
    mavenCentral()
    gradlePluginPortal()
}

dependencies {
    implementation("org.jetbrains.dokka:dokka-gradle-plugin:2.2.0")
}

Dokka 컨벤션 플러그인 설정하기 (Set up the Dokka convention plugin)

buildSrc 디렉터리를 설정한 뒤 Dokka 컨벤션 플러그인을 설정해요.

• 컨벤션 플러그인을 담을 buildSrc/src/main/kotlin/dokka-convention.gradle.kts 파일을 만들어요.
• dokka-convention.gradle.kts 파일에 다음 스니펫을 추가해요.

plugins {
    id("org.jetbrains.dokka")
}

dokka {
    // The shared configuration goes here
}

모든 하위 프로젝트에 공통인 공유 Dokka 구성을 dokka {} 블록 안에 추가해야 해요. 또한 Dokka 버전을 지정할 필요는 없어요. 버전은 이미 buildSrc/build.gradle.kts 파일에 설정되어 있으니까요.

하위 프로젝트에 컨벤션 플러그인 적용하기 (Apply the convention plugin to your subprojects)

각 하위 프로젝트의 build.gradle.kts 파일에 추가해서 하위 프로젝트 전체에 Dokka 컨벤션 플러그인을 적용해요.

plugins {
    id("dokka-convention")
}

수동 구성 (Manual configuration)

프로젝트가 컨벤션 플러그인을 사용하지 않는다면, 같은 dokka {} 블록을 각 하위 프로젝트에 수동으로 복사해서 동일한 Dokka 구성 패턴을 재사용할 수 있어요.

• 모든 하위 프로젝트의 build.gradle.kts 파일에 Dokka 플러그인을 적용해요.

plugins {
    id("org.jetbrains.dokka") version "2.2.0"
}

• 각 하위 프로젝트의 dokka {} 블록에서 공유 구성을 선언해요. 구성을 중앙 집중화하는 컨벤션 플러그인이 없기 때문에, 하위 프로젝트에서 원하는 구성은 무엇이든 중복해서 작성해야 해요. 자세한 내용은 구성 옵션을 참고하세요.

상위 프로젝트 구성 (Parent project configuration)

멀티 프로젝트 빌드에서는 루트 프로젝트에서 전체 문서에 적용되는 설정을 구성할 수 있어요. 여기에는 출력 형식 정의, 출력 디렉터리, 문서 하위 프로젝트 이름, 모든 하위 프로젝트의 문서 집계 및 기타 구성 옵션이 포함될 수 있어요.

plugins {
    id("org.jetbrains.dokka") version "2.2.0"
}

dokka {
    // Sets properties for the whole project
    dokkaPublications.html {
        moduleName.set("My Project")
        outputDirectory.set(layout.buildDirectory.dir("docs/html"))
        includes.from("README.md")
    }

    dokkaSourceSets.configureEach {
        documentedVisibilities.set(setOf(VisibilityModifier.Public)) // OR documentedVisibilities(VisibilityModifier.Public)
    }
}

// Aggregates subproject documentation
dependencies {
    dokka(project(":childProjectA"))
    dokka(project(":childProjectB"))
}

추가로, 각 하위 프로젝트는 커스텀 구성이 필요하면 고유한 dokka {} 블록을 가질 수 있어요. 다음 예시에서 하위 프로젝트는 Dokka 플러그인을 적용하고, 커스텀 하위 프로젝트 이름을 설정하며, README.md 파일에서 추가 문서를 포함해요.

// subproject/build.gradle.kts
plugins {
    id("org.jetbrains.dokka")
}

dokka {
    dokkaPublications.html {
        moduleName.set("Child Project A")
        includes.from("README.md")
    }
}