Dokka 外掛程式
本指南適用於 Dokka Gradle 外掛程式 (DGP) v2 模式。DGP v1 模式已不再受支援。 若要從 v1 升級至 v2 模式,請遵循遷移指南。
Dokka 從一開始就被設計為易於擴充且高度可自訂,這讓社群能夠針對開箱即用所未提供的遺漏功能或非常具體的需求來實作外掛程式。
Dokka 外掛程式的範圍相當廣泛,從支援其他程式語言原始碼到各種特殊的輸出格式應有盡有。你可以新增對自訂 KDoc 標籤或註解的支援、讓 Dokka 懂得如何轉譯 KDoc 描述中出現的不同 DSL、重新設計 Dokka 頁面的視覺效果以無縫整合至公司的網站、將其與其他工具進行整合等等。
如果你想學習如何建立 Dokka 外掛程式,請參閱開發者指南。
套用 Dokka 外掛程式
Dokka 外掛程式是以獨立構件發佈的,因此若要套用 Dokka 外掛程式,你只需要將其新增為相依性即可。接著,外掛程式就會自動擴充 Dokka——無需執行任何進一步的操作。
使用相同擴充點或以類似方式運作的外掛程式可能會互相干擾。 這可能會導致視覺錯誤、一般的未定義行為,甚至是組建失敗。然而,這不應該導致並行問題,因為 Dokka 不會公開任何可變的資料結構或物件。
如果你注意到類似的問題,建議檢查已套用了哪些外掛程式以及它們的作用。
讓我們來看看如何將 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 外掛程式:新增自訂圖片至資源中(customAssets 選項)、自訂樣式表(customStyleSheets 選項),以及修改頁尾訊息(footerMessage 選項):
若要以型別安全的方式配置 Dokka 外掛程式,請使用 dokka.pluginsConfiguration {} 區塊:
dokka {
pluginsConfiguration.html {
customAssets.from("logo.png")
customStyleSheets.from("styles.css")
footerMessage.set("(c) Your Company")
}
}有關 Dokka 外掛程式配置的範例,請參閱 Dokka 的版本控制外掛程式。
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 執行器,請使用 -pluginsConfiguration 選項,它接受形式為 fullyQualifiedPluginName=json 的 JSON 配置。
如果你需要配置多個外掛程式,可以傳入多個以 ^^ 分隔的值。
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 配置,則存在一個類似的 pluginsConfiguration 陣列,它會在 values 中接受 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\"}"
}
]
}值得關注的外掛程式
以下是一些你可能會覺得實用的著名 Dokka 外掛程式:
| 名稱 | 說明 |
|---|---|
| Android documentation plugin | 改善 Android 上的文件體驗 |
| Versioning plugin | 新增版本選擇器,並協助整理應用程式/程式庫不同版本的文件 |
| MermaidJS HTML plugin | 轉譯 KDoc 中找到的 MermaidJS 圖表和視覺化內容 |
| Mathjax HTML plugin | 美化輸出 KDoc 中找到的數學公式 |
| Kotlin as Java plugin | 從 Java 的角度呈現 Kotlin 簽章 |
| GFM plugin | 新增以 GitHub Flavoured Markdown 格式產生文件的功能 |
| Jekyll plugin | 新增以 Jekyll Flavoured Markdown 格式產生文件的功能 |
如果你是 Dokka 外掛程式作者,並希望將你的外掛程式新增至此清單中,請透過 Slack 或 GitHub 與維護人員聯絡。
