[Android] Dokka 문서화 총 정리 (+with 자동 배포)

내가 참여했던 프로젝트 <터닝 terning> 에서 컴포넌트를 모아둔 파일을 문서화하기로 하였다.

그래서 문서화를 하기 위해 노션, 깃허브 위키 등 다양한 방법을 떠올렸다.

하지만 위의 방법들은 매번 글을 쓰며 관리를 해줘야 하는 단점이 있었고, 이에 반해 주석만 달아도 자동으로 배포되는 기능이 있어, 이를 도입하고자 했다.

바로, Dokka이다.

 

Dokka란, Kotlin 코드를 문서화하기 위한 툴이다.

KDoc 언어로 작성하면 된다.

 

Dokka 사용

먼저, Dokka를 사용하기 위해 라이브러리를 추가해준다.

[versions]
dokka = "1.9.0"

[plugins]
dokka = {id = "org.jetbrains.dokka", version.ref = "dokka"}

 

이를 project 그래들 파일에 추가해준다.

plugins {
    alias(libs.plugins.dokka) apply false
}

 

그리고 문서화가 필요한 모듈의 그래들 파일에 추가해준다.

<terning> 같은 경우는 core 모듈에서 디자인 시스템 로직을 작성했기 때문에 core 모듈에 추가해주었다.

plugins {
    alias(libs.plugins.dokka)
}

android {
...
}

tasks.dokkaHtml.configure {
    dokkaSourceSets {
        named("main") {
            noAndroidSdkLink.set(false)
        }
    }
}

 

마지막으로 아래의 명령어를 터미널에 작성해주면 끝!!!

./gradlew dokkaHtml

 

여기서 주의해야 할 점은 코틀린 버전과 Dokka 버전이 같아야 한다.

그렇지 않으면 아래와 같은 에러가 발생한다ㅜㅜ

 

그러면 core/build/dokka/html 루트에 index.html 파일이 생성된 것을 확인할 수 있다.

 

 

자동 배포

하지만 위 사진에서 볼 수 있다시피, 파일에서 웹을 여는 것이기 때문에 다른 사람들은 접근이 불가한 문제가 발생한다.

그래서 배포를 해줘야만 한다.

 

이를 위해 먼저 야믈 파일을 작성해준다.

.github/workflows/dokka.yml 에 파일을 작성해주면 된다.

• BRANCH에 배포할 브렌치를 작성해준다.
• FOLDER에 배포 대상의 파일 위치를 작성해준다.

name: TerningPoint DesignSystem CI

on:
  push:
    branches: [ develop ]

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: Set up JDK 18
        uses: actions/setup-java@v4
        with:
          java-version: 18
          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: gh-pages
          FOLDER: core/build/dokka/html

 

 

그 다음, 레포의 Settings의 Pages 탭에서 위에서 지정한 배포할 브렌치를 설정해준다.

 

위 야믈 파일에서는 gh-pages 브렌치로 설정을 해줬기 때문에 

gh-pages와 /(root)를 선택하고 Save를 누르면 된다.

 

이때, 파일을 배포할 gh-pages 브렌치는 먼저 생성을 해줘야 지정이 가능하다!

 

 

트러블 슈팅

다 된 줄 알았으나.. 여기서부터 문제가 발생한다..

바로 아래와 같은 에러가 발생한 것.

 

위 에러는 GitHub Actions가 원격 리포지토리에 대한 접근 권한이 없어서 발생한 것이다.

따라서 이를 해결해주기 위해서는 아래의 순서를 따르면 된다.

• 레포의 Settings에서 Actions 탭으로 이동
• General 섹션에서 Workflow permissions을 확인
• Read and write permissions 옵션이 선택되어 있는지 확인

이 설정이 되어 있어야 GitHub Actions가 레포에 푸시할 수 있게 된다.

여기서 한 가지 더 유의점은, 오가니제이션의 Settings 권한을 먼저 Read and write permissions 로 바꿔줘야 오가니제이션의 레포도 권한을 바꿀 수 있다!!!

 

 

그러면 자동적으로 배포 성공!!

 

인줄 알았으나 문제가 하나 더 있다.

 

로컬 프로퍼티를 사용하는 프로젝트의 경우, dokka.yml 파일이 로컬 프로퍼티에 접근을 못해 에러가 발생한다.

 

이는 다음과 같이 해결해주면 된다.

• GitHub Secrets에 로컬 프로퍼티의 변수들 추가
• 야믈 파일에서 local.properties 파일을 생성
• local.properties 파일에 필요한 환경 변수 값을 추가

최종 dokka.yml 파일은 다음과 같다.

name: TerningPoint DesignSystem CI

on:
  push:
    branches: [ develop ]

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

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

      - name: Change gradlew permissions
        run: chmod +x gradlew

      - name: Create Local Properties
        run: touch local.properties

      - name: Set Local Properties
        env:
          BASE_URL: ${{ secrets.BASE_URL }}
          NATIVE_APP_KEY: ${{ secrets.NATIVE_APP_KEY }}
          NATIVEAPPKEY: ${{ secrets.NATIVEAPPKEY }}
        run: |
          echo base.url=\"$BASE_URL\" >> local.properties
          echo native.app.key=\"$NATIVE_APP_KEY\" >> local.properties
          echo nativeAppKey=\"$NATIVEAPPKEY\" >> local.properties

      - name: Build Documentation
        run: ./gradlew dokkaHtml

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

 

 

➕ 추가로, 잠시 배포를 멈추고 싶다면

Actions에서 해당 파일을 누르고 Disable workflow를 눌러주면 된다.

 

문서화 꾸미기

여기서 문서를 더 꾸며주고 싶다면

모듈단의 그래들에서 작성해준 코드에 docs.md라는 파일을 포함하는 코드를 더해준다.

tasks.dokkaHtml.configure {
    dokkaSourceSets {
        named("main") {
            includes.from("docs.md")
            noAndroidSdkLink.set(false)
        }
    }
}

 

docs.md 파일에 아래와 같은 규칙으로 작성해주면 된다.

# 패키지 이름
패키지 설명

 

 

ex) 작성 예시

# Package com.terning.core.designsystem.component.bottomsheet
바텀시트가 있는 패키지입니다.

# Package com.terning.core.designsystem.component.button
버튼이 있는 패키지입니다.

 

 

최종 배포 링크

위와 같은 순서로 개발을 진행하면 깃허브에 링크가 잘 뜨는 것을 확인할 수 있다!

아래는 터닝에서 배포한 링크이다. 

https://teamterning.github.io/Terning-Android/

designsystem