From e7954db37470f869aa898726e3eef66c9efa4f01 Mon Sep 17 00:00:00 2001 From: Marvin Ramin Date: Mon, 10 Sep 2018 07:37:12 +0200 Subject: [PATCH] update documentation to use new detekt gradle plugin (#1095) * update documentation to use new detekt gradle plugin * remove reference to profiles/input path for idea DSL --- .github/CONTRIBUTING.md | 2 +- README.md | 15 ++-- docs/index.md | 36 ++++++---- docs/pages/gettingstarted/cli.md | 27 ++++--- docs/pages/gettingstarted/gradletask.md | 2 +- docs/pages/gettingstarted/groovydsl.md | 85 +++++++--------------- docs/pages/gettingstarted/kotlindsl.md | 86 ++++++++++++++++++++--- docs/pages/gettingstarted/mavenanttask.md | 2 +- 8 files changed, 150 insertions(+), 105 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 6a9c742da..486b1da24 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -3,7 +3,7 @@ - Read [this article](https://chris.beams.io/posts/git-commit/) before writing commit messages - Copy the file `commit-msg` to `.git/hooks` - Use `gradle build -x dokka` to build the source but exclude documentation jar generating to save time. -- `gradle detektCheck` should not report any errors +- `gradle detekt` should not report any errors - This repo uses tabs! Make sure your code is properly formatted. - Use idea-code-style.xml for coding style . - We use [Spek](https://github.com/spekframework/spek) for testing. diff --git a/README.md b/README.md index cab45daeb..2ef956aad 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ Visit https://arturbosch.github.io/detekt/ for installation guides, release note #### with gradle -```gradle +```kotlin buildscript { repositories { jcenter() @@ -53,14 +53,15 @@ buildscript { } plugins { - id "io.gitlab.arturbosch.detekt" version "1.0.0.[version]" + id("io.gitlab.arturbosch.detekt").version("[version]") } detekt { - version = "1.0.0.[version]" - defaultProfile { - input = file("src/main/kotlin") + detekt { + version = "[version]" + input = files("src/main/kotlin") filters = ".*/resources/.*,.*/build/.*" + config = files("path/to/config.yml") } } ``` @@ -70,9 +71,9 @@ detekt { detekt itself provides a wrapper over [KtLint](https://github.com/shyiko/ktlint) as a `formatting` rule set which can be easily added to the gradle configuration: -```gradle +```kotlin dependencies { - detekt "io.gitlab.arturbosch.detekt:detekt-formatting:1.0.0.[version]" + detekt "io.gitlab.arturbosch.detekt:detekt-formatting:[version]" } ``` diff --git a/docs/index.md b/docs/index.md index 41431a6c7..20bce3a22 100644 --- a/docs/index.md +++ b/docs/index.md @@ -27,9 +27,9 @@ summary: ### Quick Start with Gradle -Apply following configuration to your gradle build file and run `gradle detektCheck`: +Apply following configuration to your gradle build file and run `gradle detekt`: -```groovy +```kotlin buildscript { repositories { jcenter() @@ -37,15 +37,14 @@ buildscript { } plugins { - id "io.gitlab.arturbosch.detekt" version "1.0.0.[version]" + id("io.gitlab.arturbosch.detekt").version("[version]") } detekt { - version = "1.0.0.[version]" - defaultProfile { - input = file("src/main/kotlin") - filters = ".*/resources/.*,.*/build/.*" - } + version = "[version]" + input = files("src/main/kotlin") + filters = ".*/resources/.*,.*/build/.*" + config = files("path/to/config.yml") } ``` @@ -55,13 +54,20 @@ If you want to change the default behaviour of detekt rules, first generate your Then reference the config inside the defaultProfile-closure: -`config = file("default-detekt-config.yml")` +`config = files("default-detekt-config.yml")` -If you need a textual report, specify the output directory and the reports name in the `defaultProfile`-closure: - -``` -output = file("reports") -outputName = "detekt" +To enable/disable detekt reports and to configure their output directories edit the `detekt { }` closure: +```kotlin +detekt { + xml { + enabled = true + destination = file("path/to/destination.xml") + } + html { + enabled = true + destination = file("path/to/destination.html") + } +} ``` ### Adding more rule sets @@ -71,7 +77,7 @@ which can be easily added to the gradle configuration: ```gradle dependencies { - detekt "io.gitlab.arturbosch.detekt:detekt-formatting:1.0.0.[version]" + detekt "io.gitlab.arturbosch.detekt:detekt-formatting:[version]" } ``` diff --git a/docs/pages/gettingstarted/cli.md b/docs/pages/gettingstarted/cli.md index 4d4b4b05b..94d778cec 100644 --- a/docs/pages/gettingstarted/cli.md +++ b/docs/pages/gettingstarted/cli.md @@ -18,18 +18,19 @@ The following parameters are shown when `--help` is entered. The `--input`/`-i` Usage: detekt [options] Options: --baseline, -b - If a baseline xml file is passed in, only new code smells not in the + If a baseline xml file is passed in, only new code smells not in the baseline are printed in the console. --config, -c - Path to the config file (path/to/config.yml). + Path to the config file (path/to/config.yml). Multiple configuration + files can be specified with ',' or ';' as separator. --config-resource, -cr Path to the config resource on detekt's classpath (path/to/config.yml). --create-baseline, -cb - Treats current analysis findings as a smell baseline for future detekt - runs. + Treats current analysis findings as a smell baseline for future detekt + runs. Default: false --debug - Debugs given ktFile by printing its elements. + Prints extra information about configurations and extensions. Default: false --disable-default-rulesets, -dd Disables default rule sets. @@ -43,14 +44,20 @@ Usage: detekt [options] Shows the usage. * --input, -i Input paths to analyze. - --output, -o - Directory where output reports are stored. - --output-name, -on - The base name for output reports is derived from this parameter. --parallel - Enables parallel compilation of source files. Should only be used if the + Enables parallel compilation of source files. Should only be used if the analyzing project has more than ~200 kotlin files. Default: false --plugins, -p Extra paths to plugin jars separated by ',' or ';'. + --print-ast + Prints the AST for given [input] file. Must be no directory. + Default: false + --report, -r + Generates a report for given 'report-id' and stores it on given 'path'. + Entry should consist of: [report-id:path-to-store-report]+ + --run-rule + Specify a rule by [RuleSet:Rule] pattern and run it on input. + + ``` diff --git a/docs/pages/gettingstarted/gradletask.md b/docs/pages/gettingstarted/gradletask.md index 5069528b9..bb3fe82f2 100644 --- a/docs/pages/gettingstarted/gradletask.md +++ b/docs/pages/gettingstarted/gradletask.md @@ -33,6 +33,6 @@ task detekt(type: JavaExec) { } dependencies { - detekt 'io.gitlab.arturbosch.detekt:detekt-cli:1.0.0.[version]' + detekt 'io.gitlab.arturbosch.detekt:detekt-cli:[version]' } ``` diff --git a/docs/pages/gettingstarted/groovydsl.md b/docs/pages/gettingstarted/groovydsl.md index 687e34fa2..1b042df6d 100644 --- a/docs/pages/gettingstarted/groovydsl.md +++ b/docs/pages/gettingstarted/groovydsl.md @@ -36,7 +36,7 @@ buildscript { } plugins { - id "io.gitlab.arturbosch.detekt" version "1.0.0.[version]" + id "io.gitlab.arturbosch.detekt" version "[version]" } ``` @@ -49,29 +49,13 @@ buildscript { maven { url "https://plugins.gradle.org/m2/" } } dependencies { - classpath "gradle.plugin.io.gitlab.arturbosch.detekt:detekt-gradle-plugin:1.0.0.[version]" + classpath "gradle.plugin.io.gitlab.arturbosch.detekt:detekt-gradle-plugin:[version]" } } apply plugin: "io.gitlab.arturbosch.detekt" ``` -##### Configuration when using Kotlin DSL -For gradle version >= 4.1 - -```kotlin -import io.gitlab.arturbosch.detekt.DetektExtension - -buildscript { - repositories { - jcenter() - } -} -plugins { - id("io.gitlab.arturbosch.detekt").version("1.0.0.[version]") -} -``` - ##### Configuration for Android projects When using Android make sure to have detekt configured in the project level build.gradle file. @@ -80,20 +64,20 @@ You can configure the plugin in the same way as indicated above. ```groovy buildscript { repositories { -// maven { url "https://plugins.gradle.org/m2/" } + maven { url "https://plugins.gradle.org/m2/" } jcenter() } dependencies { - classpath 'com.android.tools.build:gradle:2.3.3' -// classpath "gradle.plugin.io.gitlab.arturbosch.detekt:detekt-gradle-plugin:1.0.0.[version]" + classpath 'com.android.tools.build:gradle:[version]' + classpath "gradle.plugin.io.gitlab.arturbosch.detekt:detekt-gradle-plugin:[version]" } } plugins { - id "io.gitlab.arturbosch.detekt" version "1.0.0.[version]" + id "io.gitlab.arturbosch.detekt" version "[version]" } -//apply plugin: 'io.gitlab.arturbosch.detekt' +apply plugin: 'io.gitlab.arturbosch.detekt' ``` @@ -101,25 +85,26 @@ plugins { ```groovy detekt { - toolVersion = "1.0.0.[version]" // When unspecified the latest detekt version found, will be used. Override to stay on the same version. - input = files( // The directories where detekt looks for input files. Defaults to `files("src/main/java", "src/main/kotlin")` + toolVersion = "[version]" // Version of the Detekt CLI that will be used. When unspecified the latest detekt version found will be used. Override to stay on the same version. + input = files( // The directories where detekt looks for input files. Defaults to `files("src/main/java", "src/main/kotlin")`. "src/main/kotlin", "gensrc/main/kotlin" ) parallel = false // Runs detekt in parallel. Can lead to speedups in larger projects. `false` by default. - config = file("path/to/config.yml") // Define the detekt configuration you want to use. Defaults to the default detekt configuration. - baseline = file("path/to/baseline.xml") // Specifying a baseline file will ignore all findings that are saved in the baseline file. - filters = '' // Regular expression of paths that should be excluded separated by `;`. Defaults to `.*/test/.*;.*Test.kt';.*Spec.kt` + config = files("path/to/config.yml") // Define the detekt configuration(s) you want to use. Defaults to the default detekt configuration. + baseline = file("path/to/baseline.xml") // Specifying a baseline file. All findings stored in this file in subsequent runs of detekt. + filters = '' // Regular expression of paths that should be excluded separated by `;`. disableDefaultRuleSets = false // Disables all default detekt rulesets and will only run detekt with custom rules defined in `plugins`. `false` by default. plugins = "other/optional/ruleset.jar" // Additional jar file containing custom detekt rules. debug = false // Adds debug output during task execution. `false` by default. - reportsDir = file('build/detekt-reports') // Output directory where the reports are created. Defaults to `build/reports/detekt` reports { - xml.enabled = true // Enable/Disable XML report (default: true) - xml.destination file("build/reports/detekt.xml") // Path where XML report will be stored (default: `build/reports/detekt/detekt.xml`) - html { // Alternatively as nested closure + xml { + enabled = true // Enable/Disable XML report (default: true) + destination = file("build/reports/detekt.xml") // Path where XML report will be stored (default: `build/reports/detekt/detekt.xml`) + } + html { enabled = true // Enable/Disable HTML report (default: true) - destination file("build/reports/detekt.html") // Path where HTML report will be stored (default: `build/reports/detekt/detekt.html`) + destination = file("build/reports/detekt.html") // Path where HTML report will be stored (default: `build/reports/detekt/detekt.html`) } } } @@ -130,30 +115,13 @@ detekt { Custom tasks for alternative configurations or different source sets can be defined by creating a custom task that uses the type `Detekt`. -###### Kotlin DSL -```kotlin -task("detektFailFast") { - description = "Runs a failfast detekt build." - - input = files("src/main/kotlin", "src/test/kotlin") - config = file("config.yml") - debug = true - reports { - xml { - destination = file("build/reports/failfast.xml") - } - html.destination = file("build/reports/failfast.html") - } -} -``` - ###### Groovy DSL ```groovy task detektFailFast(type: io.gitlab.arturbosch.detekt.Detekt) { description = "Runs a failfast detekt build." input = files("src/main/java") - config = file("$rootDir/config.yml") + config = files("$rootDir/config.yml") debug = true reports { xml { @@ -164,15 +132,14 @@ task detektFailFast(type: io.gitlab.arturbosch.detekt.Detekt) { } ``` -##### Configure a local idea for detekt +##### Configure a local IDEA for detekt -- download the community edition of [Intellij IDEA](https://www.jetbrains.com/idea/download/) -- extract the file to your preferred location eg. `~/.idea` -- let detekt know about idea inside the `detekt-closure` -- extract `code-style.xml` and `inpect.xml` from idea settings (`Settings>CodeStyle>Scheme` and `Settings>Inspections>Profile`) -- run `detektIdeaFormat` or `detektIdeaInspect` -- all parameters in the following detekt-closure are mandatory for both tasks -- make sure that current or default profile have an input path specified! +- Download the community edition of [IntelliJ IDEA](https://www.jetbrains.com/idea/download/) +- Extract the file to your preferred location eg. `~/.idea` +- Let detekt know about idea inside the `detekt-closure` +- Extract `code-style.xml` and `inpect.xml` from idea settings (`Settings>CodeStyle>Scheme` and `Settings>Inspections>Profile`) +- Run `detektIdeaFormat` or `detektIdeaInspect` +- All parameters in the following detekt-closure are mandatory for both tasks ```groovy String userHome = System.getProperty("user.home") diff --git a/docs/pages/gettingstarted/kotlindsl.md b/docs/pages/gettingstarted/kotlindsl.md index 69ef882b9..0de436ec1 100644 --- a/docs/pages/gettingstarted/kotlindsl.md +++ b/docs/pages/gettingstarted/kotlindsl.md @@ -11,6 +11,9 @@ summary: All information from Gradle Groovy DSL are still valid, but the DSL to apply the plugin changes slightly. + +##### Configuration when using Kotlin DSL + For gradle version >= 4.1 ```kotlin @@ -22,18 +25,79 @@ buildscript { } } plugins { - id("io.gitlab.arturbosch.detekt").version("1.0.0.[version]") + id("io.gitlab.arturbosch.detekt").version("[version]") } -configure { - version = "1.0.0.[version]" - profile("main", Action { - input = "src/main/kotlin" - config = "detekt.yml" - filters = ".*/resources/.*,.*/tmp/.*" - output = "reports" - outputName = "detekt-report" - baseline = "reports/baseline.xml" - }) +detekt { + toolVersion = "[version]" // Version of the Detekt CLI that will be used. When unspecified the latest detekt version found will be used. Override to stay on the same version. + input = files( // The directories where detekt looks for input files. Defaults to `files("src/main/java", "src/main/kotlin")`. + "src/main/kotlin", + "gensrc/main/kotlin" + ) + parallel = false // Runs detekt in parallel. Can lead to speedups in larger projects. `false` by default. + config = files("path/to/config.yml") // Define the detekt configuration(s) you want to use. Defaults to the default detekt configuration. + baseline = file("path/to/baseline.xml") // Specifying a baseline file. All findings stored in this file in subsequent runs of detekt. + filters = '' // Regular expression of paths that should be excluded separated by `;`. + disableDefaultRuleSets = false // Disables all default detekt rulesets and will only run detekt with custom rules defined in `plugins`. `false` by default. + plugins = "other/optional/ruleset.jar" // Additional jar file containing custom detekt rules. + debug = false // Adds debug output during task execution. `false` by default. + reports { + xml { + enabled = true // Enable/Disable XML report (default: true) + destination = file("build/reports/detekt.xml") // Path where XML report will be stored (default: `build/reports/detekt/detekt.xml`) + } + html { + enabled = true // Enable/Disable HTML report (default: true) + destination = file("build/reports/detekt.html") // Path where HTML report will be stored (default: `build/reports/detekt/detekt.html`) + } + } } ``` + +##### Defining custom detekt task + +Custom tasks for alternative configurations or different source sets can be defined by creating a custom task that +uses the type `Detekt`. + +###### Kotlin DSL +```kotlin +task("detektFailFast") { + description = "Runs a failfast detekt build." + + input = files("src/main/kotlin", "src/test/kotlin") + config = files("$rootDir/config.yml") + debug = true + reports { + xml { + destination = file("build/reports/failfast.xml") + } + html.destination = file("build/reports/failfast.html") + } +} +``` + + +##### Configure a local IDEA for detekt + +- Download the community edition of [IntelliJ IDEA](https://www.jetbrains.com/idea/download/) +- Extract the file to your preferred location eg. `~/.idea` +- Let detekt know about idea inside the `detekt-closure` +- Extract `code-style.xml` and `inpect.xml` from idea settings (`Settings>CodeStyle>Scheme` and `Settings>Inspections>Profile`) +- Run `detektIdeaFormat` or `detektIdeaInspect` +- All parameters in the following detekt-closure are mandatory for both tasks + +```kotlin +val userHome = System.getProperty("user.home") + +detekt { + idea { + path = "$userHome/.idea" + codeStyleScheme = "$userHome/.idea/idea-code-style.xml" + inspectionsProfile = "$userHome/.idea/inspect.xml" + report = "project.projectDir/reports" + mask = "*.kt," + } +} +``` + +For more information on using idea as a headless formatting/inspection tool see [here](https://www.jetbrains.com/help/idea/working-with-intellij-idea-features-from-command-line.html). diff --git a/docs/pages/gettingstarted/mavenanttask.md b/docs/pages/gettingstarted/mavenanttask.md index 5de5c7861..d8717e771 100644 --- a/docs/pages/gettingstarted/mavenanttask.md +++ b/docs/pages/gettingstarted/mavenanttask.md @@ -50,7 +50,7 @@ summary: io.gitlab.arturbosch.detekt detekt-cli - 1.0.0.[version] + [version]