-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* add logo * update readme * update readme * update gitattributes * git attributes update * add link to output formats * update version number in tests
- Loading branch information
Showing
13 changed files
with
484 additions
and
101 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,15 +1,51 @@ | ||
| # | ||
| # https://help.github.com/articles/dealing-with-line-endings/ | ||
| # | ||
| # https://github.com/alexkaratarakis/gitattributes | ||
|
|
||
| * text=auto | ||
|
|
||
| # The above will handle all files NOT found below | ||
|
|
||
| *.json text | ||
| *.toml text | ||
| *.xml text | ||
| *.yaml text | ||
| *.yml text | ||
| .editorconfig text | ||
| .env text | ||
|
|
||
| # Documentation | ||
| *.md text diff=markdown | ||
| *.txt text | ||
| LICENSE text | ||
|
|
||
| # JVM | ||
| *.java text diff=java | ||
| *.kt text diff=kotlin | ||
| *.kts text diff=kotlin | ||
| *.properties text | ||
| *.jar binary | ||
|
|
||
|
|
||
| # Linux start script should use lf | ||
| /gradlew text eol=lf | ||
| gradlew text eol=lf | ||
| *.bash text eol=lf | ||
| *.sh text eol=lf | ||
|
|
||
| # These are Windows script files and should use crlf | ||
| *.bat text eol=crlf | ||
| *.bat text eol=crlf | ||
| *.cmd text eol=crlf | ||
|
|
||
| # SVG treated as an asset (binary) by default. | ||
| *.svg text | ||
|
|
||
| # Exclude external libs from GitHub language stats https://github.com/github/linguist/blob/v7.24.1/docs/overrides.md | ||
| examples/** linguist-documentation | ||
| examples/*/dokka linguist-vendored | ||
| modules/dokkatoo-plugin-integration-tests/projects/**dokka/ linguist-vendored | ||
| modules/dokkatoo-plugin-integration-tests/projects/**dokkatoo/ linguist-documentation | ||
|
|
||
| # Exclude files from exporting | ||
|
|
||
| .gitattributes export-ignore | ||
| .gitignore export-ignore | ||
| .gitkeep export-ignore |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,135 +1,211 @@ | ||
| [](https://github.com/adamko-dev/dokkatoo/blob/main/LICENSE) | ||
| [](https://github.com/adamko-dev/dokkatoo/tree/artifacts#readme) | ||
| [](https://plugins.gradle.org/search?term=dokkatoo) | ||
| [](https://github.com/adamko-dev/dokkatoo/tree/artifacts#readme) | ||
|
|
||
| # Dokkatoo | ||
| [](https://github.com/adamko-dev/dokkatoo) | ||
|
|
||
| Dokkatoo generates documentation for Kotlin Gradle projects (based on Dokka). | ||
| [Dokkatoo](https://github.com/adamko-dev/dokkatoo) is a Gradle plugin that generates documentation | ||
| for your Kotlin projects. | ||
|
|
||
| * Compatible with Gradle Build Cache | ||
| * Compatible with Gradle Configuration Cache (Soon™) | ||
| Under the hood it uses [Dokka](https://kotlinlang.org/docs/dokka-introduction.html), | ||
| the API documentation engine for Kotlin. | ||
|
|
||
| ###### Why Dokkatoo? | ||
|
|
||
| If | ||
| [Dokka already has a Gradle plugin](https://kotlinlang.org/docs/dokka-gradle.html), | ||
| then what is Dokkatoo for? | ||
|
|
||
| Dokkatoo has a number of improvements over the existing Dokka Gradle Plugin: | ||
|
|
||
| * Compatible with [Gradle Build Cache](https://docs.gradle.org/current/userguide/build_cache.html) | ||
| * Compatible with | ||
| [Gradle Configuration Cache](https://docs.gradle.org/current/userguide/configuration_cache.html) | ||
| (soon!) | ||
| * Safe cross-project sharing and aggregation | ||
| * Parallel execution | ||
|
|
||
| ## Status | ||
| ### Status | ||
|
|
||
| Dokkatoo has basic functionality, and can generate documentation for single-projects and | ||
| multimodule projects. | ||
|
|
||
| Experimental early release, lots of things are broken and undocumented. | ||
| Be aware that many of things are untested, broken, and undocumented. Please | ||
| [create an issue](https://github.com/adamko-dev/dokkatoo/issues) | ||
| if something is not as you'd expect, or like. | ||
|
|
||
| ## Usage | ||
|
|
||
| ### Applying the Gradle plugin | ||
| Dokkatoo is published on the [Gradle Plugin Portal](https://plugins.gradle.org/search?term=dokkatoo). | ||
|
|
||
| Dokkatoo is published to a GitHub branch which must be defined as a Gradle Plugin repository. | ||
| ### Quick start | ||
|
|
||
| For example, using the Plugin Management DSL | ||
| 1. Apply the appropriate plugin for any formats you'd like to generate. | ||
|
|
||
| ```kts | ||
| // settings.gradle.kts | ||
| For example, HTML and Javadoc | ||
| ```kotlin | ||
| // build.gradle.kts | ||
|
|
||
| plugins { | ||
| // only generate HTML and Javadoc | ||
| id("dev.adamko.dokkatoo-html") version "$dokkatooVersion" | ||
| id("dev.adamko.dokkatoo-javadoc") version "$dokkatooVersion" | ||
| //id("dev.adamko.dokkatoo-gfm") version "$dokkatooVersion" | ||
| //id("dev.adamko.dokkatoo-jekyll") version "$dokkatooVersion" | ||
| } | ||
| ``` | ||
| Or all formats | ||
|
|
||
| pluginManagement { | ||
| repositories { | ||
| gradlePluginPortal() | ||
| mavenCentral() | ||
| maven("https://raw.githubusercontent.com/adamko-dev/dokkatoo/artifacts/m2/") | ||
| } | ||
| } | ||
| ``` | ||
| ```kotlin | ||
| // build.gradle.kts | ||
|
|
||
| plugins { | ||
| // generate all formats - HTML, Jekyll, Javadoc, and GFM (GitHub Flavoured Markdown) | ||
| id("dev.adamko.dokkatoo") version "$dokkatooVersion" | ||
| } | ||
| ``` | ||
| [Read more about the available formats in the Dokka docs](https://github.com/Kotlin/dokka#output-formats). | ||
| 2. Run the generation task | ||
|
|
||
| The Dokkatoo plugin can be then be applied to any Gradle project. | ||
| ```shell | ||
| ./gradlew dokkatooGenerate | ||
| ``` | ||
|
|
||
| ```kts | ||
| 3. View the results in `./build/dokka/` | ||
|
|
||
|
|
||
| #### Configuring Dokkatoo | ||
|
|
||
| Once the Dokkatoo plugin is applied to a project, it can be configuring using the `dokkatoo {}` DSL. | ||
|
|
||
| Here is an example - it is not exhaustive and does not cover all functionality. | ||
|
|
||
| ```kotlin | ||
| // build.gradle.kts | ||
|
|
||
| plugins { | ||
| id("dev.adamko.dokkatoo") version "0.0.1-SNAPSHOT" | ||
| id("dev.adamko.dokkatoo-html") version "$dokkatooVersion" | ||
| } | ||
| ``` | ||
|
|
||
| Alternatively, the Maven Coordinates of the Dokkatoo plugin can be defined in an included build | ||
|
|
||
| ```kts | ||
| // buildSrc/settings.gradle.kts | ||
|
|
||
| pluginManagement { | ||
| repositories { | ||
| gradlePluginPortal() | ||
| mavenCentral() | ||
| maven("https://raw.githubusercontent.com/adamko-dev/dokkatoo/artifacts/m2/") | ||
| dokkatoo { | ||
| moduleName.set("Basic Project") | ||
| dokkatooSourceSets.configureEach { | ||
| documentedVisibilities( | ||
| DokkaConfiguration.Visibility.PUBLIC, | ||
| DokkaConfiguration.Visibility.PROTECTED, | ||
| ) | ||
| suppressedFiles.from(file("src/main/kotlin/it/suppressedByPath")) | ||
| perPackageOption { | ||
| matchingRegex.set("it.suppressedByPackage.*") | ||
| suppress.set(true) | ||
| } | ||
| perPackageOption { | ||
| matchingRegex.set("it.overriddenVisibility.*") | ||
| documentedVisibilities( | ||
| DokkaConfiguration.Visibility.PRIVATE | ||
| ) | ||
| } | ||
| } | ||
| dokkatooPublications.configureEach { | ||
| suppressObviousFunctions.set(true) | ||
| pluginsConfiguration.create("org.jetbrains.dokka.base.DokkaBase") { | ||
| serializationFormat.set(DokkaConfiguration.SerializationFormat.JSON) | ||
| values.set( | ||
| """ | ||
| { | ||
| "customStyleSheets": [ | ||
| "${file("./customResources/logo-styles.css").invariantSeparatorsPath}", | ||
| "${file("./customResources/custom-style-to-add.css").invariantSeparatorsPath}" | ||
| ], | ||
| "customAssets": [ | ||
| "${file("./customResources/custom-resource.svg").invariantSeparatorsPath}" | ||
| ] | ||
| } | ||
| """.trimIndent() | ||
| ) | ||
| } | ||
| suppressObviousFunctions.set(false) | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| #### Combining subprojects | ||
|
|
||
| Dokkatoo can aggregate documentation from subprojects. | ||
|
|
||
| To do this, apply the Dokkatoo plugin in all subprojects that should be documented. | ||
|
|
||
| In the aggregating project, depend on the other subprojects. | ||
|
|
||
| ```kts | ||
| // buildSrc/build.gradle.kts | ||
| // ./build.gradle.kts | ||
|
|
||
| plugins { | ||
| `kotlin-dsl` | ||
| id("dev.adamko.dokkatoo-html") version "$dokkatooVersion" | ||
| } | ||
|
|
||
| dependencies { | ||
| implementation("dev.adamko.dokkatoo:dokkatoo-plugin:0.0.1-SNAPSHOT") | ||
| // aggregate both subproject-hello and subproject-world | ||
| // the subprojects must also have Dokkatoo applied | ||
| dokkatoo(projects(":subproject-hello")) | ||
| dokkatoo(projects(":subproject-world")) | ||
| } | ||
| ``` | ||
|
|
||
| Then the plugin can be applied in any Gradle project, without needing to define a version | ||
|
|
||
| ```kts | ||
| // build.gradle.kts | ||
| Run the Dokkatoo generation task. | ||
|
|
||
| plugins { | ||
| id("dev.adamko.dokkatoo") // version defined in buildSrc/build.gradle.kts | ||
| } | ||
| ```shell | ||
| ./gradlew :dokkatooGeneratePublicationHtml | ||
| ``` | ||
|
|
||
| #### Dokkatoo Gradle Tasks | ||
| Only run the task in the aggregating project (prefix the task name with the subproject path) | ||
| so that Dokkatoo doesn't generate documentation in other subprojects (it won't cause problems, but | ||
| it will be slower.) | ||
|
|
||
| Any Dokkatoo tasks can be run to generate a documentation site in the | ||
| `build/dokkatoo` directory. | ||
| Dokkatoo will then generate documentation into `./docs/build/dokka/` | ||
|
|
||
| ```shell | ||
| # generate all sites | ||
| ./gradlew dokkatooGenerate | ||
|
|
||
| # only generate a single format | ||
| ./gradlew dokkatooGenerateHtml | ||
| ./gradlew dokkatooGenerateGfm | ||
| ./gradlew dokkatooGenerateJekyll | ||
| ./gradlew dokkatooGenerateJavadoc | ||
| ``` | ||
| ### Migrating from Dokka Gradle Plugin | ||
|
|
||
| ### Combining subprojects | ||
| Dokkatoo is not a drop-in replacement for the Dokka Gradle Plugin, and requires migration. | ||
|
|
||
| Any subproject can depend on other subprojects to aggregate them all into a single Dokka | ||
| Publication. | ||
| When Dokkatoo matures, a guide will be made available. For now, check the | ||
| [example projects](./examples/README.md) for comparative examples. | ||
|
|
||
| ```kts | ||
| // ./build.gradle.kts | ||
| ###### Apply both Dokka Gradle Plugin and Dokkatoo | ||
|
|
||
| For help in migrating from the Dokka Gradle Plugin to Dokkatoo, you can still apply both plugins - | ||
| just make sure to update the Dokkatoo output directory! | ||
|
|
||
| ```kotlin | ||
| // build.gradle.kts | ||
|
|
||
| plugins { | ||
| id("dev.adamko.dokkatoo") version "0.0.1-SNAPSHOT" | ||
| id("org.jetbrains.dokka") version "$dokkaVersion" | ||
| id("dev.adamko.dokkatoo-html") version "$dokkatooVersion" | ||
| } | ||
|
|
||
| dependencies { | ||
| // aggregate both subproject-hello and subproject-world | ||
| // the subprojects must also have Dokkatoo applied | ||
| dokkatoo(projects(":subproject-hello")) | ||
| dokkatoo(projects(":subproject-world")) | ||
| dokkatoo { | ||
| // update the output directory, so it doesn't clash with the Dokka plugin! | ||
| dokkatooPublicationDirectory.set(layout.buildDirectory.dir("dokkatoo")) | ||
| } | ||
| ``` | ||
|
|
||
| ### Specific formats | ||
| ### Snapshot releases | ||
|
|
||
| By default, the Dokkatoo plugin sets up publication of multiple formats: HTML, | ||
| GFM (GitHub Flavoured Markdown), Jekyll, and Javadoc. If you only want to generate one format, then | ||
| specific plugins are provided: | ||
| Snapshot versions of Dokkatoo are available. They are published to a GitHub branch, which must be | ||
| added as a | ||
| [custom Gradle Plugin repository](https://docs.gradle.org/current/userguide/plugins.html#sec:custom_plugin_repositories) | ||
|
|
||
| ```kts | ||
| // ./build.gradle.kts | ||
| // settings.gradle.kts | ||
|
|
||
| plugins { | ||
| // apply any one plugin to automatically configure a single format | ||
| id("dev.adamko.dokkatoo-html") | ||
| id("dev.adamko.dokkatoo-gfm") | ||
| id("dev.adamko.dokkatoo-jekyll") | ||
| id("dev.adamko.dokkatoo-javadoc") | ||
| pluginManagement { | ||
| repositories { | ||
| gradlePluginPortal() | ||
| mavenCentral() | ||
|
|
||
| // add the Dokkatoo snapshot repository | ||
| maven("https://raw.githubusercontent.com/adamko-dev/dokkatoo/artifacts/m2/") | ||
| } | ||
| } | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
21 changes: 21 additions & 0 deletions
21
buildSrc/src/main/kotlin/buildsrc/utils/initIdeProjectLogo.kt
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| package buildsrc.utils | ||
|
|
||
| import org.gradle.api.Project | ||
|
|
||
| /** Sets a logo for project IDEs */ | ||
| fun Project.initIdeProjectLogo() { | ||
| val logoSvg = rootProject.layout.projectDirectory.file("media/img/logo.svg") | ||
| val ideaDir = rootProject.layout.projectDirectory.dir(".idea") | ||
|
|
||
| if ( | ||
| logoSvg.asFile.exists() | ||
| && ideaDir.asFile.exists() | ||
| && !ideaDir.file("icon.png").asFile.exists() | ||
| && !ideaDir.file("icon.svg").asFile.exists() | ||
| ) { | ||
| copy { | ||
| from(logoSvg) { rename { "icon.svg" } } | ||
| into(ideaDir) | ||
| } | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
2 changes: 1 addition & 1 deletion
2
examples/multimodule-example/dokkatoo/parentProject/build.gradle.kts
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.