Dokka 플러그인

Dokka 플러그인 (Dokka plugins)

Dokka는 처음부터 확장하기 쉽고 커스터마이즈가 자유롭게 설계되었어요. 그래서 기본 제공 기능에 없는, 아주 구체적인 기능은 커뮤니티가 플러그인으로 만들어 쓸 수 있어요. 이번에는 Dokka 플러그인을 어떻게 적용하고 설정하는지 살펴볼게요.

출처: Dokka plugins

본문

이 가이드는 Dokka Gradle 플러그인(DGP) v2 모드에 해당해요. DGP v1 모드는 더 이상 지원되지 않으니, v1에서 v2로 올리려면 Migration guide를 따라가면 돼요.

Dokka는 처음부터 쉽게 확장 가능하고 높게 커스터마이즈할 수 있도록 만들어졌어요. 그래서 커뮤니티가 기본으로 제공되지 않는, 빠져 있거나 아주 특별한 기능을 위한 플러그인을 구현할 수 있어요.

Dokka 플러그인의 범위는 다른 프로그래밍 언어 소스 지원부터 이색적인 출력 형식까지 아주 넓어요. 자신만의 KDoc 태그나 어노테이션을 지원하도록 만들 수도 있고, KDoc 설명에서 찾은 다양한 DSL을 Dokka가 렌더링하도록 가르칠 수도 있어요. Dokka 페이지를 회사 웹사이트와 자연스럽게 통합되도록 시각적으로 재설계하거나, 다른 도구와 연동할 수도 있어요.

Dokka 플러그인을 만드는 방법을 배우고 싶다면 Developer guides 문서를 참고해요.

Dokka 플러그인 적용하기

Dokka 플러그인은 별도의 아티팩트로 배포되어요. 그래서 Dokka 플러그인을 적용하려면 의존성으로 추가하기만 하면 돼요. 그러면 플러그인이 알아서 Dokka를 확장해요 — 추가 조치가 필요 없어요.

같은 확장 지점을 쓰거나 비슷하게 동작하는 플러그인끼리는 서로 간섭할 수 있어요. 이로 인해 시각적인 버그, 일반적으로 정의되지 않은 동작, 나아가 빌드 실패까지 발생할 수 있어요. 다만 Dokka는 가변 데이터 구조나 객체를 노출하지 않기 때문에 동시성(concurrency) 문제가 생기지는 않아요.

이런 문제가 보이면 어떤 플러그인이 적용되어 있는지, 그들이 무엇을 하는지 확인해 보는 게 좋아요.

mathjax 플러그인을 프로젝트에 적용하는 방법을 살펴볼게요:

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

dependencies {
    dokkaPlugin("org.jetbrains.dokka:mathjax-plugin")
}

내장 플러그인(HTML, Javadoc 등)은 항상 자동으로 적용돼요. 의존성으로 선언할 필요 없이 설정만 하면 돼요.
멀티 모듈 프로젝트(멀티 프로젝트 빌드)를 문서화할 때는 서브프로젝트 간 Dokka 설정과 플러그인을 공유해야 해요.

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

dependencies {
    dokkaPlugin 'org.jetbrains.dokka:mathjax-plugin'
}

멀티 프로젝트 빌드를 문서화할 때는 서브프로젝트 간 Dokka 설정을 공유해야 해요.

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    ...
    <configuration>
        <dokkaPlugins>
            <plugin>
                <groupId>org.jetbrains.dokka</groupId>
                <artifactId>mathjax-plugin</artifactId>
                <version>2.2.0</version>
            </plugin>
        </dokkaPlugins>
    </configuration>
</plugin>

CLI 러너를 커맨드 라인 옵션으로 쓴다면, Dokka 플러그인을 .jar 파일로 -pluginsClasspath에 넘겨야 해요:

java -jar dokka-cli-2.2.0.jar \
     -pluginsClasspath "./dokka-base-2.2.0.jar;...;./mathjax-plugin-2.2.0.jar" \
     ...

JSON 설정을 쓴다면 Dokka 플러그인을 pluginsClasspath 아래에 지정해야 해요.

{
  ...
  "pluginsClasspath": [
    "./dokka-base-2.2.0.jar",
    "...",
    "./mathjax-plugin-2.2.0.jar"
  ],
  ...
}

Dokka 플러그인 설정하기

Dokka 플러그인도 자기만의 설정 옵션을 가질 수 있어요. 어떤 옵션이 있는지는 사용 중인 플러그인의 문서를 확인하면 돼요.

내장 HTML 플러그인을 어떻게 설정하는지 살펴볼게요. assets에 커스텀 이미지를 추가하고(customAssets 옵션), 커스텀 스타일 시트(customStyleSheets 옵션)를 넣고, 푸터 메시지를 바꿔 보는(footerMessage 옵션) 구성이에요:

타입 안전한 방식으로 Dokka 플러그인을 설정하려면 dokka.pluginsConfiguration {} 블록을 사용해요:

dokka {
    pluginsConfiguration.html {
        customAssets.from("logo.png")
        customStyleSheets.from("styles.css")
        footerMessage.set("(c) Your Company")
    }
}

Dokka 플러그인 설정의 예시는 Dokka의 versioning 플러그인에서 볼 수 있어요.

Dokka는 커스텀 플러그인을 설정해서 기능을 확장하고 문서 생성 과정을 수정할 수 있어요.

dokka {
    pluginsConfiguration {
        html {
            customAssets.from("logo.png")
            customStyleSheets.from("styles.css")
            footerMessage.set("(c) Your Company")
        }
    }
}

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    ...
    <configuration>
        <pluginsConfiguration>
            <!-- Fully qualified plugin name -->
            <org.jetbrains.dokka.base.DokkaBase>
                <!-- Options by name -->
                <customAssets>
                    <asset>${project.basedir}/my-image.png</asset>
                </customAssets>
                <customStyleSheets>
                    <stylesheet>${project.basedir}/my-styles.css</stylesheet>
                </customStyleSheets>
                <footerMessage>(c) MyOrg 2022 Maven</footerMessage>
            </org.jetbrains.dokka.base.DokkaBase>
        </pluginsConfiguration>
    </configuration>
</plugin>

CLI 러너를 커맨드 라인 옵션으로 쓴다면, fullyQualifiedPluginName=json 형태의 JSON 설정을 받는 -pluginsConfiguration 옵션을 사용해요.

여러 플러그인을 설정해야 한다면 ^^로 구분해서 여러 값을 넘길 수 있어요.

java -jar dokka-cli-2.2.0.jar \
     ...
     -pluginsConfiguration "org.jetbrains.dokka.base.DokkaBase={\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg CLI\"}"

JSON 설정을 쓴다면, values에서 JSON 설정을 받는 비슷한 pluginsConfiguration 배열이 있어요.

{
  "moduleName": "Dokka Example",
  "pluginsConfiguration": [
    {
      "fqPluginName": "org.jetbrains.dokka.base.DokkaBase",
      "serializationFormat": "JSON",
      "values": "{\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg\"}"
    }
  ]
}

주목할 만한 플러그인 (Notable plugins)

유용하게 쓸 수 있는 Dokka 플러그인 몇 가지를 소개할게요:

Name	Description
Android documentation plugin	Android 환경에서 문서 경험을 개선해요
Versioning plugin	버전 선택기를 추가하고 애플리케이션/라이브러리의 여러 버전 문서를 정리할 수 있게 도와줘요
MermaidJS HTML plugin	KDoc에서 찾은 MermaidJS 다이어그램과 시각화를 렌더링해요
Mathjax HTML plugin	KDoc에서 찾은 수학 내용을 보기 좋게 출력해요
Kotlin as Java plugin	Kotlin 시그니처를 Java의 관점에서 본 모습으로 렌더링해요
GFM plugin	GitHub Flavoured Markdown 형식으로 문서를 생성할 수 있게 해줘요
Jekyll plugin	Jekyll Flavoured Markdown 형식으로 문서를 생성할 수 있게 해줘요

Dokka 플러그인 작성자라면 이 목록에 자신의 플러그인을 추가하고 싶을 수도 있어요. Slack이나 GitHub를 통해 메인테이너에게 연락하세요.

더 알아보기

Dokka를 Javadoc 형식으로 쓰는 방법은 Dokka Javadoc 문서를 참고해요.
모듈·패키지 문서를 제공하는 법은 모듈 및 패키지 문서에서 배워요.