Dokka를 활용한 코드 문서화 (with 배포)

프로젝트를 진행하다보면 팀원들간의 코드 공유, 혹은 코드를 이해하기 위해 코드를 문서화하는 일이 필요할 때가 있습니다.

주석을 통해 코드를 문서화하는 것도 좋지만, 코드를 문서화하는 툴을 사용하면 더욱 편리하게 코드를 문서화할 수 있습니다.

보통 Java에서는 Javadoc을 사용하고, Kotlin에서는 KDoc을 사용합니다.

하지만 이번에는 Kotlin에서 사용할 수 있는 Dokka를 사용해보겠습니다.

Dokka란?

Dokka는 Kotlin을 위한 문서화 툴로, Kotlin 코드를 문서화하기 위한 툴입니다.

Dokka는 Kotlin 코드를 HTML, Markdown, Javadoc 등의 형식으로 변환할 수 있습니다.

Dokka는 Gradle 플러그인으로 제공되며, Gradle을 통해 쉽게 프로젝트에 적용할 수 있습니다.

Dokka 설치

Dokka를 사용하기 위해서는 Gradle 플러그인을 설치해야 합니다.

build.gradle 파일에 아래와 같이 추가해줍니다.

plugins {
    id "org.jetbrains.dokka" version "1.9.10"
}

그리고 현재 2024년 6월 15일 기준으로 Dokka와 Jackson의 버전이 충돌이 나는 문제가 있습니다.

따라서 다음과 같이 Jackson의 버전을 2.15.3으로 고정해주어야 합니다.

(dependency 근처에 추가해주면 됩니다.)

configurations.matching { it.name.startsWith("dokka") }.configureEach {
    resolutionStrategy.eachDependency {
        if (requested.group.startsWith("com.fasterxml.jackson")) {
            useVersion("2.15.3")
        }
    }
}

Dokka 사용

Dokka를 사용하기 위해서는 다음과 같이 명령어를 입력하면 됩니다.

./gradlew dokkaHtml

위 명령어를 입력하면 build/dokka/html 디렉토리에 문서화된 HTML 파일이 생성됩니다.

만약 Markdown 파일로 변환하고 싶다면 다음과 같이 명령어를 입력하면 됩니다.

./gradlew dokkaMarkdown

생성 결과

개발자 모드로 접속해보면 확인할 수 있지만 왼쪽 사이드에는 목차가 들어가게 됩니다.
하지만 File기반으로 접속하기 때문에 정상적으로 작동하지 않습니다.

따라서 웹 서버를 띄워서 확인하면 정상적으로 작동합니다.

아래에서 쉽게 Github Pages에 배포하는 방법을 소개하겠습니다.

설명(주석) 작성하기

Dokka를 사용하기 위해서는 주석을 작성해야 합니다.

주석은 JavaDoc과 비슷하게 작성하면 됩니다.

/**
 * 이 클래스는 사람을 나타내는 클래스입니다.
 * @property name 사람의 이름
 * @property age 사람의 나이
 */
class Person(
    val name: String,
    val age: Int
) {
    /**
     * 이 함수는 사람의 이름을 출력합니다.
     */
    fun printName() {
        println(name)
    }
}

패키지에 대한 설명을 작성하고 싶다면 docs.md 파일을 작성하면 됩니다.

# 패키지명

패키지에 대한 설명을 작성합니다.

예시

# Module TODO Swing Application

해당 문서는 Swing을 이용한 Java, kotlin 어플리케이션을 개발하는 방법에 대한 문서입니다.

# Package org.example

Main 클래스가 존재하는 패키지입니다.

# Package org.example.common

공통적으로 사용되는 클래스들이 존재하는 패키지입니다.

Font, Color, Dimension 등의 상수값을 정의하고, 공통적으로 사용되는 메소드를 정의합니다.

Dokka 배포 (GitHub Pages)

Dokka로 문서화된 결과를 GitHub Pages에 배포하려면 다음과 같이 하면 됩니다.
(gradle 기준으로 작성하였습니다.)

1. 깃허브 액션 설정

.github/workflows/dokka.yml 파일을 생성하고 다음과 같이 작성합니다.

name: Docs CI

on:
  push:
    branches: ["refactor"]

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: "17"
          distribution: "temurin"

      - name: permissions
        run: chmod +x gradlew

      - name: Build Documentation
        run: ./gradlew dokkaHtml

      - name: Deploy Documentation to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          BRANCH: docs
          FOLDER: build/dokka/html

설명

1. push 이벤트가 발생하면 docs 브랜치에 배포합니다.
2. JDK 17을 사용합니다.
3. gradlew 파일에 실행 권한을 부여합니다.
4. Dokka를 사용하여 HTML 파일을 생성합니다.
5. 생성된 HTML 파일을 docs 브랜치에 배포합니다. (정적 페이지 배포 라이브러리 사용)
   brand: 배포할 브랜치
   folder: 배포할 폴더

2. GitHub Pages 설정

1. GitHub 저장소의 Settings -> Pages로 이동합니다.
2. Source를 docs 브랜치로 설정합니다.
   깃허브 액션에서 라이브러리를 자동으로 생성해줍니다.
3. /(root)로 설정합니다.
4. Save를 클릭합니다.

3. 확인

GitHub Action 탭에서 배포 과정을 확인할 수 있습니다.

배포가 완료되면 deploy 브런치에 문서가 push된 것을 확인할 수 있습니다.
그리고, deploy에 배포 된 링크를 확인가능하며 이를 통해 문서를 확인(접속)할 수 있습니다.

Github Pages 배포 결과

이번에 리팩토링 중인 프로젝트인데, Dokka를 사용하여 문서화한 결과입니다.

https://cmsong111.github.io/Restaurant-information-system/

위에서 사이드바에 나타나지 않던 목차가 정상적으로 나타나는 것을 확인할 수 있습니다.

팁

깃허브 Readme를 작성할때 아래와 같이 배포된 링크를 추가하면 좋습니다.

[![Dokka](https://img.shields.io/badge/Kdoc-7F52FF.svg?style=for-the-badge&logo=kotlin&logoColor=white)](https://cmsong111.github.io/Restaurant-information-system/)