Gradle

Настройка формата вывода документации

Можно создавать документацию API в формате HTML, Javadoc или одновременно в обоих форматах:

1. Добавьте соответствующий плагин id в блок plugins {} файла build.gradle.kts вашего проекта:

   plugins {
       // Generates HTML documentation
       id("org.jetbrains.dokka") version "2.2.0"
   
       // Generates Javadoc documentation
       id("org.jetbrains.dokka-javadoc") version "2.2.0"
   
       // Keeping both plugin IDs generates both formats
   }
   

2. Запустите соответствующую задачу Gradle.

   Ниже перечислены плагины id и задачи Gradle, соответствующие каждому формату:

   	HTML	Javadoc	Оба формата
   Плагин id	id("org.jetbrains.dokka")	id("org.jetbrains.dokka-javadoc")	Используйте плагины HTML и Javadoc
   Задача Gradle	./gradlew :dokkaGeneratePublicationHtml	./gradlew :dokkaGeneratePublicationJavadoc	./gradlew :dokkaGenerate

Если вы используете IntelliJ IDEA, может отображаться задача Gradle dokkaGenerateHtml. Эта задача является просто псевдонимом dokkaGeneratePublicationHtml. Обе задачи выполняют одну и ту же операцию.

Объединение выходных данных документации в многопроектных сборках

Dokka может объединить документацию нескольких подпроектов в один выходной файл или публикацию.

Перед объединением документации необходимо подключить плагин Dokka во всех подпроектах, для которых можно создать документацию.

Чтобы объединить документацию нескольких подпроектов, добавьте блок dependencies {} в файл build.gradle.kts корневого проекта:

dependencies {
    dokka(project(":childProjectA:"))
    dokka(project(":childProjectB:"))
}

Предположим, что проект имеет следующую структуру:

.
└── parentProject/
    ├── childProjectA/
    │   └── demo/
    │       └── ChildProjectAClass.kt
    └── childProjectB/
        └── demo/
            └── ChildProjectBClass.kt

Созданная документация объединяется следующим образом:

Дополнительные сведения см. в нашем примере многопроектной сборки.

turbo-lib/build/dokka/html/turbo-lib/maths/

// /turbo-lib/maths/build.gradle.kts

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

dokka {
    // Overrides the subproject directory
    modulePath.set("maths")
}

Настройка однопроектной сборки

Однопроектные сборки обычно содержат только один файл build.gradle.kts или build.gradle в корне проекта. Они могут быть одноцелевыми или многоплатформенными и обычно имеют следующую структуру:

.
├── build.gradle.kts
└── src/
    └── main/
        └── kotlin/
            └── HelloWorld.kt

.
├── build.gradle.kts
└── src/
    ├── commonMain/
    │   └── kotlin/
    │       └── Common.kt
    ├── jvmMain/
    │   └── kotlin/
    │       └── JvmUtils.kt
    └── nativeMain/
        └── kotlin/
            └── NativeUtils.kt

.
├── build.gradle
└── src/
    └── main/
        └── kotlin/
            └── HelloWorld.kt

.
├── build.gradle
└── src/
    ├── commonMain/
    │   └── kotlin/
    │       └── Common.kt
    ├── jvmMain/
    │   └── kotlin/
    │       └── JvmUtils.kt
    └── nativeMain/
        └── kotlin/
            └── NativeUtils.kt

Подключите плагин Dokka Gradle в корневом файле build.gradle.kts и настройте его с помощью DSL верхнего уровня dokka {}:

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

dokka {
    dokkaPublications.html {
        moduleName.set("MyProject")
        outputDirectory.set(layout.buildDirectory.dir("documentation/html"))
        includes.from("README.md")
   }

    dokkaSourceSets.main {
        sourceLink {
            localDirectory.set(file("src/main/kotlin"))
            remoteUrl.set(URI("https://github.com/your-repo"))
            remoteLineSuffix.set("#L")
        }
    }
}

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

dokka {
    dokkaPublications {
        html {
            moduleName.set("MyProject")
            outputDirectory.set(layout.buildDirectory.dir("documentation/html"))
            includes.from("README.md")
        }
    }

    dokkaSourceSets {
        named("main") {
            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl.set(new URI("https://github.com/your-repo"))
                remoteLineSuffix.set("#L")
            }
        }
    }
}

Эта конфигурация подключает Dokka к проекту, задаёт каталог для выходных данных документации и определяет основной набор исходного кода. Её можно расширить, добавив пользовательские ресурсы, фильтры видимости или конфигурации плагинов в тот же блок dokka {}. Дополнительную информацию см. в разделе Параметры конфигурации.

Настройка многопроектной сборки

Многопроектные сборки обычно содержат несколько вложенных файлов build.gradle.kts и имеют структуру, похожую на следующую:

.
├── build.gradle.kts
├── settings.gradle.kts
├── subproject-A/
│   ├── build.gradle.kts
│   └── src/
│       └── main/
│           └── kotlin/
│               └── HelloFromA.kt
└── subproject-B/
    ├── build.gradle.kts
    └── src/
        └── main/
            └── kotlin/
                └── HelloFromB.kt

.
├── build.gradle
├── settings.gradle
├── subproject-A/
│   ├── build.gradle
│   └── src/
│       └── main/
│           └── kotlin/
│               └── HelloFromA.kt
└── subproject-B/
    ├── build.gradle
    └── src/
        └── main/
            └── kotlin/
                └── HelloFromB.kt

Для документации однопроектных и многопроектных сборок используется одна и та же модель конфигурации на основе DSL верхнего уровня dokka {}.

Существует два способа настроить Dokka в многопроектных сборках:

• Общая конфигурация с помощью плагина соглашений (рекомендуется): создание плагина соглашений и его подключение ко всем подпроектам. Это позволяет централизовать настройки Dokka.

• Ручная настройка: подключение плагина Dokka и повторение одного и того же блока dokka {} в каждом подпроекте. Плагины соглашений не требуются.

Настроив подпроекты, можно объединить их документацию в один выходной файл. Дополнительную информацию см. в разделе Объединение выходных данных документации в многопроектных сборках.

plugins {
    id("dokka-convention")
}

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

dokka {
    // Sets properties for the whole project
    dokkaPublications.html {
        moduleName.set("My Project")
        outputDirectory.set(layout.buildDirectory.dir("docs/html"))
        includes.from("README.md")
    }

    dokkaSourceSets.configureEach {
        documentedVisibilities.set(setOf(VisibilityModifier.Public)) // OR documentedVisibilities(VisibilityModifier.Public)    
    }
}

// Aggregates subproject documentation
dependencies {
    dokka(project(":childProjectA"))
    dokka(project(":childProjectB"))
}

// subproject/build.gradle.kts
plugins {
    id("org.jetbrains.dokka")
}

dokka {
    dokkaPublications.html {
        moduleName.set("Child Project A")
        includes.from("README.md")
    }
}