CLI
어떤 이유로든 Gradle 또는 Maven 빌드 도구를 사용할 수 없는 경우, Dokka는 문서 생성을 위한 명령줄(CLI) 러너를 제공합니다.
비교하자면, CLI 러너는 Dokka용 Gradle 플러그인과 동일하거나 오히려 더 많은 기능을 제공합니다. 하지만 자동 구성(autoconfiguration)이 없기 때문에, 특히 멀티플랫폼 및 멀티모듈 환경에서는 설정하기가 상당히 더 까다롭습니다.
시작하기
CLI 러너는 실행 가능한 별도의 아티팩트로 Maven Central에 배포됩니다.
Maven Central에서 찾거나 직접 다운로드할 수 있습니다.
컴퓨터에 dokka-cli-2.2.0.jar 파일을 저장한 후, -help 옵션과 함께 실행하면 사용 가능한 모든 구성 옵션과 해당 설명을 확인할 수 있습니다.
java -jar dokka-cli-2.2.0.jar -help-sourceSet과 같은 일부 중첩된 옵션에 대해서도 동작합니다.
java -jar dokka-cli-2.2.0.jar -sourceSet -help문서 생성하기
사전 요구사항
의존성을 관리해 주는 빌드 도구가 없으므로, 필요한 의존성 .jar 파일을 직접 제공해야 합니다.
모든 출력 형식에 공통으로 필요한 의존성은 다음과 같습니다.
| 그룹 | 아티팩트 | 버전 | 링크 |
|---|---|---|---|
org.jetbrains.dokka | dokka-base | 2.2.0 | 다운로드 |
org.jetbrains.dokka | analysis-kotlin-symbols | 2.2.0 | 다운로드 |
다음은 HTML 출력 형식에 추가로 필요한 의존성입니다.
| 그룹 | 아티팩트 | 버전 | 링크 |
|---|---|---|---|
org.jetbrains.kotlinx | kotlinx-html-jvm | 0.8.0 | 다운로드 |
org.freemarker | freemarker | 2.3.31 | 다운로드 |
명령줄 옵션으로 실행
명령줄 옵션을 전달하여 CLI 러너를 구성할 수 있습니다.
최소한 다음 옵션들은 제공해야 합니다.
-pluginsClasspath- 다운로드한 의존성들의 절대/상대 경로 목록(세미콜론;으로 구분)-sourceSet- 문서를 생성할 소스 코드의 절대 경로-outputDir- 문서가 출력될 디렉터리의 절대/상대 경로
java -jar dokka-cli-2.2.0.jar \
-pluginsClasspath "./dokka-base-2.2.0.jar;./analysis-kotlin-symbols-2.2.0.jar;./kotlinx-html-jvm-0.8.0.jar;./freemarker-2.3.31.jar" \
-sourceSet "-src /home/myCoolProject/src/main/kotlin" \
-outputDir "./dokka/html"위 예제를 실행하면 HTML 출력 형식으로 문서가 생성됩니다.
자세한 구성 정보는 명령줄 옵션을 참고하세요.
JSON 구성으로 실행
JSON을 사용하여 CLI 러너를 구성할 수도 있습니다. 이 경우 첫 번째이자 유일한 인수로 JSON 구성 파일의 절대/상대 경로를 제공해야 합니다. 다른 모든 구성 옵션은 해당 파일에서 파싱됩니다.
java -jar dokka-cli-2.2.0.jar dokka-configuration.json최소한 다음과 같은 JSON 구성 파일이 필요합니다.
{
"outputDir": "./dokka/html",
"sourceSets": [
{
"sourceSetID": {
"scopeId": "moduleName",
"sourceSetName": "main"
},
"sourceRoots": [
"/home/myCoolProject/src/main/kotlin"
]
}
],
"pluginsClasspath": [
"./dokka-base-2.2.0.jar",
"./kotlinx-html-jvm-0.8.0.jar",
"./analysis-kotlin-symbols-2.2.0.jar",
"./freemarker-2.3.31.jar"
]
}자세한 내용은 JSON 구성 옵션을 참고하세요.
기타 출력 형식
기본적으로 dokka-base 아티팩트에는 HTML 출력 형식만 포함되어 있습니다.
다른 모든 출력 형식은 Dokka 플러그인으로 구현되어 있습니다. 이를 사용하려면 플러그인 클래스패스에 추가해야 합니다.
예를 들어, 실험적 기능인 GFM 출력 형식으로 문서를 생성하려면 gfm-plugin의 JAR(다운로드)을 다운로드하여 pluginsClasspath 구성 옵션에 전달해야 합니다.
명령줄 옵션을 사용하는 경우:
java -jar dokka-cli-2.2.0.jar \
-pluginsClasspath "./dokka-base-2.2.0.jar;...;./gfm-plugin-2.2.0.jar" \
...JSON 구성을 사용하는 경우:
{
...
"pluginsClasspath": [
"./dokka-base-2.2.0.jar",
"...",
"./gfm-plugin-2.2.0.jar"
],
...
}pluginsClasspath에 GFM 플러그인을 전달하면 CLI 러너가 GFM 출력 형식으로 문서를 생성합니다.
자세한 내용은 GFM 및 Javadoc 페이지를 참고하세요.
명령줄 옵션
사용 가능한 모든 명령줄 옵션 목록과 자세한 설명을 보려면 다음을 실행하세요.
java -jar dokka-cli-2.2.0.jar -help요약 목록:
| 옵션 | 설명 |
|---|---|
moduleName | 프로젝트/모듈의 이름입니다. |
moduleVersion | 문서화할 버전입니다. |
outputDir | 출력 디렉터리 경로이며, 기본값은 ./dokka입니다. |
sourceSet | Dokka 소스 세트에 대한 구성입니다. 중첩된 구성 옵션을 포함합니다. |
pluginsConfiguration | Dokka 플러그인에 대한 구성입니다. |
pluginsClasspath | Dokka 플러그인 및 그 의존성 JAR 목록입니다. 세미콜론으로 구분된 여러 경로를 허용합니다. |
offlineMode | 네트워크를 통해 원격 파일/링크를 확인할지 여부입니다. |
failOnWarning | Dokka에서 경고나 오류가 발생했을 때 문서 생성을 실패 처리할지 여부입니다. |
delayTemplateSubstitution | 일부 요소의 대체를 지연할지 여부입니다. 멀티모듈 프로젝트의 증분 빌드에서 사용됩니다. |
noSuppressObviousFunctions | kotlin.Any 및 java.lang.Object에서 상속된 함수와 같이 명백한(obvious) 함수를 억제(제외)할지 여부입니다. |
includes | 모듈 및 패키지 문서가 포함된 Markdown 파일 목록입니다. 세미콜론으로 구분된 여러 값을 허용합니다. |
suppressInheritedMembers | 특정 클래스에서 명시적으로 재정의되지 않은 상속 멤버를 억제(제외)할지 여부입니다. |
globalPackageOptions | "matchingRegex,-deprecated,-privateApi,+warnUndocumented,+suppress;+visibility:PUBLIC;..." 형식의 전역 패키지 구성 옵션 목록입니다. 세미콜론으로 구분된 여러 값을 허용합니다. |
globalLinks | {url}^{packageListUrl} 형식의 전역 외부 문서 링크입니다. ^^로 구분된 여러 값을 허용합니다. |
globalSrcLink | 코드를 탐색할 수 있는 소스 디렉터리와 웹 서비스 간의 전역 매핑입니다. 세미콜론으로 구분된 여러 경로를 허용합니다. |
helpSourceSet | 중첩된 -sourceSet 구성에 대한 도움말을 출력합니다. |
loggingLevel | 로깅 레벨입니다. 사용 가능한 값: DEBUG, PROGRESS, INFO, WARN, ERROR. |
help, h | 사용법 정보를 출력합니다. |
소스 세트 옵션
중첩된 -sourceSet 구성에 사용할 수 있는 명령줄 옵션 목록을 보려면 다음을 실행하세요.
java -jar dokka-cli-2.2.0.jar -sourceSet -help요약 목록:
| 옵션 | 설명 |
|---|---|
sourceSetName | 소스 세트의 이름입니다. |
displayName | 내부 및 외부에서 모두 사용되는 소스 세트의 표시 이름입니다. |
classpath | 분석 및 대화형 샘플을 위한 클래스패스입니다. 세미콜론으로 구분된 여러 경로를 허용합니다. |
src | 분석 및 문서화할 소스 코드 루트입니다. 세미콜론으로 구분된 여러 경로를 허용합니다. |
dependentSourceSets | moduleName/sourceSetName 형식의 종속 소스 세트 이름입니다. 세미콜론으로 구분된 여러 값을 허용합니다. |
samples | 샘플 함수가 포함된 디렉터리 또는 파일 목록입니다. 세미콜론으로 구분된 여러 경로를 허용합니다. |
includes | 모듈 및 패키지 문서가 포함된 Markdown 파일 목록입니다. 세미콜론으로 구분된 여러 경로를 허용합니다. |
documentedVisibilities | 문서화할 가시성 한정자입니다. 세미콜론으로 구분된 여러 값을 허용합니다. 사용 가능한 값: PUBLIC, PRIVATE, PROTECTED, INTERNAL, PACKAGE. |
reportUndocumented | 문서화되지 않은 선언을 보고할지 여부입니다. |
noSkipEmptyPackages | 빈 패키지에 대한 페이지를 생성할지 여부입니다. |
skipDeprecated | 지원 중단된(deprecated) 선언을 건너뛸지 여부입니다. |
jdkVersion | JDK Javadoc에 링크할 때 사용할 JDK 버전입니다. |
languageVersion | 분석 및 샘플 환경을 설정하는 데 사용되는 언어 버전입니다. |
apiVersion | 분석 및 샘플 환경을 설정하는 데 사용되는 Kotlin API 버전입니다. |
noStdlibLink | Kotlin 표준 라이브러리로 연결되는 링크를 생성할지 여부입니다. |
noJdkLink | JDK Javadoc으로 연결되는 링크를 생성할지 여부입니다. |
suppressedFiles | 문서화에서 제외할 파일 경로입니다. 세미콜론으로 구분된 여러 경로를 허용합니다. |
suppressAnnotatedWith | 특정 어노테이션이 지정된 선언을 제외하기 위한 어노테이션 정규화된 이름(FQN) 목록입니다. 세미콜론으로 구분된 여러 값을 허용합니다. |
analysisPlatform | 분석 설정에 사용되는 플랫폼입니다. |
perPackageOptions | matchingRegexp,-deprecated,-privateApi,+warnUndocumented,+suppress;... 형식의 패키지 소스 세트 구성 목록입니다. 세미콜론으로 구분된 여러 값을 허용합니다. |
externalDocumentationLinks | {url}^{packageListUrl} 형식의 외부 문서 링크입니다. ^^로 구분된 여러 값을 허용합니다. |
srcLink | 코드를 탐색할 수 있는 소스 디렉터리와 웹 서비스 간의 매핑입니다. 세미콜론으로 구분된 여러 경로를 허용합니다. |
JSON 구성
다음은 각 구성 섹션에 대한 몇 가지 예제와 상세 설명입니다. 페이지 하단에서 모든 구성 옵션이 적용된 예제도 확인할 수 있습니다.
일반 구성
{
"moduleName": "Dokka Example",
"moduleVersion": null,
"outputDir": "./build/dokka/html",
"failOnWarning": false,
"suppressObviousFunctions": true,
"suppressInheritedMembers": false,
"offlineMode": false,
"includes": [
"module.md"
],
"sourceLinks": [
{ "_comment": "Options are described in a separate section" }
],
"perPackageOptions": [
{ "_comment": "Options are described in a separate section" }
],
"externalDocumentationLinks": [
{ "_comment": "Options are described in a separate section" }
],
"sourceSets": [
{ "_comment": "Options are described in a separate section" }
],
"pluginsClasspath": [
"./dokka-base-2.2.0.jar",
"./kotlinx-html-jvm-0.8.0.jar",
"./analysis-kotlin-symbols-2.2.0.jar",
"./freemarker-2.3.31.jar"
]
}moduleName
모듈을 참조하는 데 사용되는 표시 이름입니다. 목차, 탐색, 로깅 등에 사용됩니다.
기본값: root
moduleVersion
모듈 버전입니다.
기본값: 비어 있음
outputDirectory
출력 형식과 관계없이 문서가 생성되는 디렉터리입니다.
기본값: ./dokka
failOnWarning
Dokka에서 경고나 오류가 발생했을 때 문서 생성을 실패 처리할지 여부입니다. 프로세스는 먼저 모든 오류와 경고가 발생할 때까지 기다립니다.
이 설정은 reportUndocumented와 함께 사용하기에 좋습니다.
기본값: false
suppressObviousFunctions
명백한(obvious) 함수를 억제(제외)할지 여부입니다.
다음과 같은 경우 함수가 명백한 것으로 간주됩니다:equals,hashCode,toString과 같이kotlin.Any,Kotlin.Enum,java.lang.Object또는java.lang.Enum에서 상속된 경우.dataClass.componentN또는dataClass.copy와 같이 컴파일러에 의해 합성(synthetic) 생성되었으며 문서가 없는 경우.
기본값: true
suppressInheritedMembers
특정 클래스에서 명시적으로 재정의되지 않은 상속 멤버를 억제(제외)할지 여부입니다.
참고: 이 옵션은 equals / hashCode / toString과 같은 함수를 억제할 수 있지만, dataClass.componentN 및 dataClass.copy와 같은 합성 함수는 억제할 수 없습니다. 이러한 함수를 제외하려면 suppressObviousFunctions를 사용하세요.
기본값: false
offlineMode
네트워크를 통해 원격 파일/링크를 확인할지 여부입니다.
여기에는 표준 라이브러리의 클래스를 클릭할 수 있도록 하는 등 외부 문서 링크를 생성하는 데 사용되는 패키지 목록(package-list)이 포함됩니다.
이 값을 true로 설정하면 특정 상황에서 빌드 시간을 크게 단축할 수 있지만, 표준 라이브러리를 포함한 의존성의 클래스/멤버 링크가 연결되지 않는 등 문서의 품질과 사용자 경험이 저하될 수 있습니다.
참고: 가져온 파일을 로컬에 캐시하고 로컬 경로로 Dokka에 제공할 수 있습니다. externalDocumentationLinks 섹션을 참고하세요.
기본값: false
includes
모듈 및 패키지 문서가 포함된 Markdown 파일 목록입니다.
지정된 파일의 내용은 파싱되어 모듈 및 패키지 설명으로 문서에 포함됩니다.
이 옵션은 패키지별로 구성할 수 있습니다.
sourceLinks
모든 소스 세트에 적용되는 소스 링크의 전역 구성입니다.
사용 가능한 옵션 목록은 소스 링크 구성을 참고하세요.
perPackageOptions
소스 세트에 관계없이 매칭된 패키지에 적용되는 전역 구성입니다.
사용 가능한 옵션 목록은 패키지별 구성을 참고하세요.
externalDocumentationLinks
소스 세트와 관계없이 사용되는 외부 문서 링크의 전역 구성입니다.
사용 가능한 옵션 목록은 외부 문서 링크 구성을 참고하세요.
pluginsClasspath
Dokka 플러그인 및 그 의존성 JAR 파일 목록입니다.
소스 세트 구성
Kotlin 소스 세트를 구성하는 방법:
{
"sourceSets": [
{
"displayName": "jvm",
"sourceSetID": {
"scopeId": "moduleName",
"sourceSetName": "main"
},
"dependentSourceSets": [
{
"scopeId": "dependentSourceSetScopeId",
"sourceSetName": "dependentSourceSetName"
}
],
"documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"],
"reportUndocumented": false,
"skipEmptyPackages": true,
"skipDeprecated": false,
"jdkVersion": 8,
"languageVersion": "1.7",
"apiVersion": "1.7",
"noStdlibLink": false,
"noJdkLink": false,
"includes": [
"module.md"
],
"analysisPlatform": "jvm",
"sourceRoots": [
"/home/ignat/IdeaProjects/dokka-debug-mvn/src/main/kotlin"
],
"classpath": [
"libs/kotlin-stdlib-2.4.21.jar",
"libs/kotlin-stdlib-common-2.4.21.jar"
],
"samples": [
"samples/basic.kt"
],
"suppressedFiles": [
"src/main/kotlin/org/jetbrains/dokka/Suppressed.kt"
],
"suppressAnnotatedWith": [
"com.example.SuppressMe"
],
"sourceLinks": [
{ "_comment": "Options are described in a separate section" }
],
"perPackageOptions": [
{ "_comment": "Options are described in a separate section" }
],
"externalDocumentationLinks": [
{ "_comment": "Options are described in a separate section" }
]
}
]
}displayName
이 소스 세트를 가리키는 데 사용되는 표시 이름입니다.
이 이름은 외부(예: 문서 독자에게 소스 세트 이름이 노출됨) 및 내부(예: reportUndocumented의 로깅 메시지) 모두에서 사용됩니다.
더 적합한 이름이 없다면 플랫폼 이름을 사용할 수 있습니다.
sourceSetID
소스 세트의 기술적 ID입니다.
documentedVisibilities
문서화해야 하는 가시성 한정자의 집합입니다.
protected/internal/private 선언을 문서화하려는 경우나, public 선언을 제외하고 내부 API만 문서화하려는 경우에 사용할 수 있습니다.
이 설정은 패키지별로 구성할 수 있습니다.
사용 가능한 값:
PUBLICPRIVATEPROTECTEDINTERNALPACKAGE
기본값: PUBLIC
reportUndocumented
documentedVisibilities 및 기타 필터로 필터링된 후 KDoc이 없는 표시 대상 선언에 대해 경고를 출력할지 여부입니다.
이 설정은 failOnWarning과 함께 사용하기에 좋습니다.
이 설정은 패키지별로 구성할 수 있습니다.
기본값: false
skipEmptyPackages
다양한 필터가 적용된 후 표시되는 선언이 전혀 없는 패키지를 건너뛸지 여부입니다.
예를 들어 skipDeprecated가 true로 설정되어 있고 패키지에 지원 중단된 선언만 포함된 경우, 빈 패키지로 간주됩니다.
CLI 러너의 기본값은 false입니다.
skipDeprecated
@Deprecated가 지정된 선언을 문서화할지 여부입니다.
이 설정은 패키지별로 구성할 수 있습니다.
기본값: false
jdkVersion
Java 타입에 대한 외부 문서 링크를 생성할 때 사용할 JDK 버전입니다.
예를 들어, 공개 선언의 시그니처에서 java.util.UUID를 사용하고 이 옵션이 8로 설정되어 있다면, Dokka는 해당 타입에 대해 JDK 8 Javadoc으로 연결되는 외부 문서 링크를 생성합니다.
languageVersion
분석 및 @sample 환경을 설정하는 데 사용되는 Kotlin 언어 버전입니다.
apiVersion
분석 및 @sample 환경을 설정하는 데 사용되는 Kotlin API 버전입니다.
noStdlibLink
Kotlin 표준 라이브러리의 API 레퍼런스 문서로 연결되는 외부 문서 링크를 생성할지 여부입니다.
참고: noStdLibLink가 false로 설정되어 있으면 링크가 생성됩니다.
기본값: false
noJdkLink
JDK Javadoc으로 연결되는 외부 문서 링크를 생성할지 여부입니다.
JDK Javadoc의 버전은 jdkVersion 옵션에 의해 결정됩니다.
참고: noJdkLink가 false로 설정되어 있으면 링크가 생성됩니다.
기본값: false
includes
모듈 및 패키지 문서가 포함된 Markdown 파일 목록입니다.
지정된 파일의 내용은 파싱되어 모듈 및 패키지 설명으로 문서에 포함됩니다.
analysisPlatform
sourceRoots
분석 및 문서화할 소스 코드 루트입니다. 디렉터리와 개별 .kt / .java 파일이 입력으로 허용됩니다.
classpath
분석 및 대화형 샘플을 위한 클래스패스입니다.
의존성에서 가져온 일부 타입이 자동으로 확인/인식되지 않을 때 유용합니다.
이 옵션은 .jar 및 .klib 파일을 모두 허용합니다.
samples
@sample KDoc 태그를 통해 참조되는 샘플 함수가 포함된 디렉터리 또는 파일 목록입니다.
suppressedFiles
문서 생성 시 억제(제외)할 파일 목록입니다.
suppressAnnotatedWith
지정된 어노테이션이 붙은 선언을 제외하기 위한 어노테이션 정규화된 이름(FQN) 목록입니다.
이 어노테이션 중 하나가 지정된 선언은 생성된 문서에서 제외됩니다.
sourceLinks
이 소스 세트에만 적용되는 소스 링크 매개변수 집합입니다.
사용 가능한 옵션 목록은 소스 링크 구성을 참고하세요.
perPackageOptions
이 소스 세트 내에서 매칭된 패키지에 적용되는 매개변수 집합입니다.
사용 가능한 옵션 목록은 패키지별 구성을 참고하세요.
externalDocumentationLinks
이 소스 세트에만 적용되는 외부 문서 링크 매개변수 집합입니다.
사용 가능한 옵션 목록은 외부 문서 링크 구성을 참고하세요.
소스 링크 구성
sourceLinks 구성 블록을 사용하면 각 선언의 시그니처에 특정 줄 번호가 포함된 remoteUrl로 연결되는 source 링크를 추가할 수 있습니다. (줄 번호는 remoteLineSuffix 설정을 통해 구성할 수 있습니다.)
이를 통해 독자는 각 선언의 소스 코드를 쉽게 찾을 수 있습니다.
예시는 kotlinx.coroutines의 count() 함수 문서를 참고하세요.
소스 링크는 모든 소스 세트에 대해 한 번에 구성하거나, 소스 세트별로 개별적으로 구성할 수 있습니다.
{
"sourceLinks": [
{
"localDirectory": "src/main/kotlin",
"remoteUrl": "https://github.com/Kotlin/dokka/tree/master/src/main/kotlin",
"remoteLineSuffix": "#L"
}
]
}localDirectory
로컬 소스 디렉터리의 경로입니다.
remoteUrl
GitHub, GitLab, Bitbucket 등 문서 독자가 접근할 수 있는 소스 코드 호스팅 서비스의 URL입니다. 이 URL은 선언의 소스 코드 링크를 생성하는 데 사용됩니다.
remoteLineSuffix
URL 뒤에 소스 코드 줄 번호를 추가하는 데 사용되는 접미사입니다. 독자가 파일뿐만 아니라 선언의 특정 줄 번호로 바로 이동할 수 있도록 돕습니다.
지정된 접미사 뒤에 줄 번호가 추가됩니다. 예를 들어, 이 옵션이 #L로 설정되어 있고 줄 번호가 10인 경우 결과 URL 접미사는 #L10이 됩니다.
주요 서비스에서 사용하는 접미사:
- GitHub:
#L - GitLab:
#L - Bitbucket:
#lines-
기본값: 비어 있음 (접미사 없음)
패키지별 구성
perPackageOptions 구성 블록을 사용하면 matchingRegex와 일치하는 특정 패키지에 대해 일부 옵션을 설정할 수 있습니다.
패키지 구성은 모든 소스 세트에 대해 한 번에 추가하거나, 소스 세트별로 개별적으로 추가할 수 있습니다.
{
"perPackageOptions": [
{
"matchingRegex": ".*internal.*",
"suppress": false,
"skipDeprecated": false,
"reportUndocumented": false,
"documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"]
}
]
}matchingRegex
패키지를 일치시키는 데 사용되는 정규식입니다.
suppress
문서 생성 시 이 패키지를 건너뛸지 여부입니다.
기본값: false
skipDeprecated
@Deprecated가 지정된 선언을 문서화할지 여부입니다.
프로젝트/모듈 수준에서 설정할 수 있습니다.
기본값: false
reportUndocumented
documentedVisibilities 및 기타 필터로 필터링된 후 KDoc이 없는 표시 대상 선언에 대해 경고를 출력할지 여부입니다.
이 설정은 failOnWarning과 함께 사용하기에 좋습니다.
소스 세트 수준에서 구성할 수 있습니다.
기본값: false
documentedVisibilities
문서화해야 하는 가시성 한정자의 집합입니다.
이 패키지 내의 protected/internal/private 선언을 문서화하려는 경우나, public 선언을 제외하고 내부 API만 문서화하려는 경우에 사용할 수 있습니다.
소스 세트 수준에서 구성할 수 있습니다.
기본값: PUBLIC
외부 문서 링크 구성
externalDocumentationLinks 블록을 사용하면 의존성의 외부 호스팅 문서로 연결되는 링크를 생성할 수 있습니다.
예를 들어 kotlinx.serialization의 타입을 사용하는 경우, 기본적으로 해당 타입은 확인되지 않은 것처럼 문서에서 클릭할 수 없습니다. 그러나 kotlinx.serialization의 API 레퍼런스 문서는 Dokka로 빌드되어 kotlinlang.org에 배포되어 있으므로, 이에 대한 외부 문서 링크를 구성할 수 있습니다. 이를 통해 Dokka가 해당 라이브러리의 타입에 대한 링크를 생성하여 올바르게 확인되고 클릭할 수 있게 됩니다.
외부 문서 링크는 모든 소스 세트에 대해 한 번에 구성하거나, 소스 세트별로 개별적으로 구성할 수 있습니다.
{
"externalDocumentationLinks": [
{
"url": "https://kotlinlang.org/api/kotlinx.serialization/",
"packageListUrl": "https://kotlinlang.org/api/kotlinx.serialization/package-list"
}
]
}url
링크할 문서의 루트 URL입니다. 반드시 끝에 슬래시(/)가 포함되어야 합니다.
Dokka는 제공된 URL에서 package-list를 자동으로 찾고 선언들을 서로 연결하기 위해 최선을 다합니다.
자동 확인에 실패하거나 로컬에 캐시된 파일을 대신 사용하려는 경우, packageListUrl 옵션 설정을 고려하세요.
packageListUrl
package-list의 정확한 위치입니다. Dokka가 자동으로 확인하는 방식 대신 사용할 수 있습니다.
패키지 목록에는 모듈 및 패키지 이름과 같은 문서 및 프로젝트 자체에 대한 정보가 포함되어 있습니다.
네트워크 요청을 방지하기 위해 로컬에 캐시된 파일 경로로 지정할 수도 있습니다.
전체 구성
다음은 사용 가능한 모든 구성 옵션이 동시에 적용된 예제입니다.
{
"moduleName": "Dokka Example",
"moduleVersion": null,
"outputDir": "./build/dokka/html",
"failOnWarning": false,
"suppressObviousFunctions": true,
"suppressInheritedMembers": false,
"offlineMode": false,
"sourceLinks": [
{
"localDirectory": "src/main/kotlin",
"remoteUrl": "https://github.com/Kotlin/dokka/tree/master/src/main/kotlin",
"remoteLineSuffix": "#L"
}
],
"externalDocumentationLinks": [
{
"url": "https://docs.oracle.com/javase/8/docs/api/",
"packageListUrl": "https://docs.oracle.com/javase/8/docs/api/package-list"
},
{
"url": "https://kotlinlang.org/api/core/kotlin-stdlib/",
"packageListUrl": "https://kotlinlang.org/api/core/kotlin-stdlib/package-list"
}
],
"perPackageOptions": [
{
"matchingRegex": ".*internal.*",
"suppress": false,
"reportUndocumented": false,
"skipDeprecated": false,
"documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"]
}
],
"sourceSets": [
{
"displayName": "jvm",
"sourceSetID": {
"scopeId": "moduleName",
"sourceSetName": "main"
},
"dependentSourceSets": [
{
"scopeId": "dependentSourceSetScopeId",
"sourceSetName": "dependentSourceSetName"
}
],
"documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"],
"reportUndocumented": false,
"skipEmptyPackages": true,
"skipDeprecated": false,
"jdkVersion": 8,
"languageVersion": "1.7",
"apiVersion": "1.7",
"noStdlibLink": false,
"noJdkLink": false,
"includes": [
"module.md"
],
"analysisPlatform": "jvm",
"sourceRoots": [
"/home/ignat/IdeaProjects/dokka-debug-mvn/src/main/kotlin"
],
"classpath": [
"libs/kotlin-stdlib-2.4.21.jar",
"libs/kotlin-stdlib-common-2.4.21.jar"
],
"samples": [
"samples/basic.kt"
],
"suppressedFiles": [
"src/main/kotlin/org/jetbrains/dokka/Suppressed.kt"
],
"suppressAnnotatedWith": [
"com.example.SuppressMe"
],
"sourceLinks": [
{
"localDirectory": "src/main/kotlin",
"remoteUrl": "https://github.com/Kotlin/dokka/tree/master/src/main/kotlin",
"remoteLineSuffix": "#L"
}
],
"externalDocumentationLinks": [
{
"url": "https://docs.oracle.com/javase/8/docs/api/",
"packageListUrl": "https://docs.oracle.com/javase/8/docs/api/package-list"
},
{
"url": "https://kotlinlang.org/api/core/kotlin-stdlib/",
"packageListUrl": "https://kotlinlang.org/api/core/kotlin-stdlib/package-list"
}
],
"perPackageOptions": [
{
"matchingRegex": ".*internal.*",
"suppress": false,
"reportUndocumented": false,
"skipDeprecated": false,
"documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"]
}
]
}
],
"pluginsClasspath": [
"./dokka-base-2.2.0.jar",
"./kotlinx-html-jvm-0.8.0.jar",
"./analysis-kotlin-symbols-2.2.0.jar",
"./freemarker-2.3.31.jar"
],
"pluginsConfiguration": [
{
"fqPluginName": "org.jetbrains.dokka.base.DokkaBase",
"serializationFormat": "JSON",
"values": "{\"separateInheritedMembers\":false,\"footerMessage\":\"© 2021 pretty good Copyright\"}"
}
],
"includes": [
"module.md"
]
}