HTML

HTML (HTML)

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

HTML은 Dokka의 기본이자 권장 출력 형식이에요. Kotlin Multiplatform, Android, Java 프로젝트를 지원해요. 추가로 HTML 형식으로 단일 및 멀티 프로젝트 빌드 모두의 문서를 작성할 수 있어요.

HTML 출력 형식의 예시는 다음 문서들을 확인해 보세요.

출처: HTML

본문

HTML 문서 생성하기 (Generate HTML documentation)

HTML은 출력 형식으로 모든 러너에서 지원돼요. HTML 문서를 생성하려면 빌드 도구 또는 러너에 따라 다음 단계를 따라 해요.

  • Gradle: 다음 태스크를 실행할 수 있어요.
  • dokkaGenerate — 적용된 플러그인을 기반으로 사용 가능한 모든 형식의 문서를 생성해요. 대부분의 사용자에게 권장되는 태스크예요. IntelliJ IDEA에서 이 태스크를 사용하면 출력으로 가는 클릭 가능한 링크가 로그로 남아요.
  • dokkaGeneratePublicationHtml — HTML 형식으로만 문서를 생성해요. 이 태스크는 출력 디렉터리를 @OutputDirectory로 노출해요. 생성된 파일을 다른 Gradle 태스크(예: 서버에 업로드, GitHub Pages 디렉터리로 이동, javadoc.jar로 패키징)에서 소비해야 할 때 이 태스크를 사용해요. 이 태스크는 일상적인 사용을 위한 것이 아니므로 의도적으로 Gradle 태스크 그룹에 나열되지 않아요.

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

  • Maven: dokka:dokka 목표(goal)를 실행해요.
  • CLI 러너: HTML 의존성을 설정한 상태로 실행해요.

NOTE: 이 형식으로 생성된 HTML 페이지는 모든 것이 올바르게 렌더링되도록 웹 서버에서 호스팅해야 해요.

GitHub Pages 같은 무료 정적 사이트 호스팅 서비스라면 무엇이든 사용할 수 있어요. 로컬에서는 IntelliJ 내장 웹 서버를 사용할 수 있어요.

구성 (Configuration)

HTML 형식은 Dokka의 기본 형식이에요. 다음 옵션으로 구성할 수 있어요.

// build.gradle.kts

dokka {
    pluginsConfiguration.html {
        customAssets.from("logo.png")
        customStyleSheets.from("styles.css")
        footerMessage.set("(c) Your Company")
        separateInheritedMembers.set(false)
        templatesDir.set(file("dokka/templates"))
        mergeImplicitExpectActualDeclarations.set(false)
    }
}

// build.gradle

dokka {
    pluginsConfiguration {
        html {
            customAssets.from("logo.png")
            customStyleSheets.from("styles.css")
            footerMessage.set("(c) Your Company")
            separateInheritedMembers.set(false)
            templatesDir.set(file("dokka/templates"))
            mergeImplicitExpectActualDeclarations.set(false)
        }
    }
}

<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>
                <separateInheritedMembers>false</separateInheritedMembers>
                <templatesDir>${project.basedir}/dokka/templates</templatesDir>
                <mergeImplicitExpectActualDeclarations>false</mergeImplicitExpectActualDeclarations>
            </org.jetbrains.dokka.base.DokkaBase>
        </pluginsConfiguration>
    </configuration>
</plugin>

명령줄 옵션으로:

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\", \"separateInheritedMembers\": false, \"templatesDir\": \"dokka/templates\", \"mergeImplicitExpectActualDeclarations\": false}
"

JSON 구성으로:

{
  "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\", \"separateInheritedMembers\": false, \"templatesDir\": \"dokka/templates\", \"mergeImplicitExpectActualDeclarations\": false}"
    }
  ]
}

구성 옵션 (Configuration options)

아래 표에는 가능한 모든 구성 옵션과 그 목적이 담겨 있어요.

옵션 설명
customAssets 문서에 함께 번들로 넣을 이미지 에셋의 경로 목록이에요. 이미지 에셋은 어떤 파일 확장자라도 가질 수 있어요. 자세한 내용은 에셋 맞춤 설정을 참고하세요.
customStyleSheets 문서에 함께 번들로 넣고 렌더링에 사용할 .css 스타일시트의 경로 목록이에요. 자세한 내용은 스타일 맞춤 설정을 참고하세요.
templatesDir 커스텀 HTML 템플릿이 담긴 디렉터리의 경로예요. 자세한 내용은 템플릿을 참고하세요.
footerMessage 푸터에 표시되는 텍스트예요.
separateInheritedMembers 불리언 옵션이에요. true로 설정하면 Dokka가 상속된 프로퍼티/함수를 별도 섹션에 렌더링해요.
mergeImplicitExpectActualDeclarations 불리언 옵션이에요. true로 설정하면 Dokka가 expect/actual로 선언되지는 않았지만 동일한 완전한 이름을 가진 선언들을 병합해요. 레거시 코드베이스에 유용할 수 있어요. 기본적으로 비활성화되어 있어요.

Dokka 플러그인 구성에 대한 자세한 내용은 Dokka 플러그인 구성하기를 참고하세요.

맞춤 설정 (Customization)

문서에 나만의 느낌을 더하려고, HTML 형식은 여러 맞춤 설정 옵션을 지원해요.

스타일 맞춤 설정 (Customize styles)

customStyleSheets 구성 옵션을 사용해 나만의 스타일시트를 쓸 수 있어요. 이들은 모든 페이지에 적용돼요.

같은 이름의 파일을 제공해서 Dokka의 기본 스타일시트를 덮어쓸 수도 있어요.

스타일시트 이름 설명
style.css 기본 스타일시트. 모든 페이지에서 쓰이는 대부분의 스타일을 담고 있어요.
logo-styles.css 헤더 로고 스타일.
prism.css PrismJS 구문 하이라이터용 스타일.

Dokka의 모든 스타일시트 소스 코드는 GitHub에서 확인할 수 있어요.

에셋 맞춤 설정 (Customize assets)

customAssets 구성 옵션을 사용해 문서에 함께 번들로 넣을 나만의 이미지를 제공할 수 있어요.

이 파일들은 <output>/images 디렉터리로 복사돼요.

customAssets 프로퍼티를 파일 컬렉션(FileCollectionFileCollection)과 함께 사용할 수 있어요.

customAssets.from("example.png", "example2.png")

같은 이름의 파일을 제공해서 Dokka의 이미지와 아이콘을 덮어쓸 수 있어요. 가장 유용하고 관련 있는 것은 헤더에 사용되는 이미지인 logo-icon.svg예요. 나머지는 대부분 아이콘이에요.

Dokka가 사용하는 모든 이미지는 GitHub에서 찾을 수 있어요.

로고 바꾸기 (Change the logo)

로고를 맞춤 설정하려면 logo-icon.svg 용 에셋을 먼저 제공하면 돼요.

로고가 마음에 들지 않거나 기본 .svg 파일 대신 .png 파일을 사용하고 싶다면 logo-styles.css 스타일시트로 맞춤 설정할 수 있어요.

이렇게 하는 예시는 커스텀 형식 예시 프로젝트를 참고하세요.

지원되는 로고 최대 크기는 폭 120픽셀, 높이 36픽셀이에요. 더 큰 이미지를 사용하면 자동으로 크기가 조정돼요.

푸터 수정하기 (Modify the footer)

footerMessage 구성 옵션으로 푸터의 텍스트를 수정할 수 있어요.

템플릿 (Templates)

Dokka는 문서 페이지를 생성하는 데 쓰이는 FreeMarker 템플릿을 수정하는 기능을 제공해요.

헤더를 완전히 바꾸거나, 나만의 배너/메뉴/검색을 추가하거나, 분석 도구를 로드하거나, 본문 스타일을 바꾸는 등의 작업을 할 수 있어요.

Dokka는 다음 템플릿을 사용해요.

템플릿 설명
base.ftl 렌더링될 모든 페이지의 일반적인 디자인을 정의해요.
includes/header.ftl 기본적으로 로고, 버전, source set 선택기, 라이트/다크 테마 전환, 검색을 담고 있는 페이지 헤더예요.
includes/footer.ftl footerMessage 구성 옵션과 저작권을 담고 있는 페이지 푸터예요.
includes/page_metadata.ftl <head> 컨테이너 안에서 사용되는 메타데이터예요.
includes/source_set_selector.ftl 헤더의 source set 선택기예요.

기본 템플릿은 base.ftl이고, 나머지 나열된 템플릿들을 모두 포함해요. Dokka의 모든 템플릿 소스 코드는 GitHub에서 찾을 수 있어요.

templatesDir 구성 옵션을 사용해 어떤 템플릿이든 덮어쓸 수 있어요. Dokka는 주어진 디렉터리 안에서 정확한 템플릿 이름을 찾아요. 사용자 정의 템플릿을 찾지 못하면 기본 템플릿을 사용해요.

변수 (Variables)

모든 템플릿 안에서 다음 변수를 사용할 수 있어요.

변수 설명
${pageName} 페이지 이름이에요.
${footerMessage} footerMessage 구성 옵션으로 설정된 텍스트예요.
${sourceSets} 멀티 플랫폼 페이지를 위한 nullable source set 목록이에요. 각 항목은 name, platform, filter 프로퍼티를 가져요.
${projectName} 프로젝트 이름이에요. template_cmd 지시문 안에서만 사용할 수 있어요.
${pathToRoot} 현재 페이지에서 루트로 가는 경로예요. 에셋을 찾는 데 유용하며 template_cmd 지시문 안에서만 사용할 수 있어요.

projectName과 pathToRoot 변수는 더 많은 컨텍스트가 필요해서 더 나중 단계에서 해석해야 하므로, template_cmd 지시문 안에서만 사용할 수 있어요.

<@template_cmd name="projectName">
    <span>${projectName}</span>
</@template_cmd>
지시문 (Directives)

Dokka가 정의한 다음 지시문도 사용할 수 있어요.

지시문 설명
<@content/> 페이지의 주요 콘텐츠예요.
<@resources/> 스크립트와 스타일시트 같은 리소스예요.
<@version/> 구성에서 가져온 하위 프로젝트 버전이에요. 버저닝 플러그인이 적용되면 버전 탐색기로 대체돼요.