Auto generate CLI options in docs (#3399)

* Auto generate CLI options

* Add tests for CliOptionsPrinter

* Update dangling URLs pointing to the old website (#3400)

* Include cli-options in markdown

.gitignore

@@ -167,4 +167,5 @@ target/
 # Avoid committing generated documentation to the repo
 /docs/pages/documentation
 /docs/pages/kdoc
+/docs/pages/gettingstarted/cli-options.md
 /docs/vendor/

detekt-generator/build.gradle.kts

@@ -10,6 +10,7 @@ dependencies {
     implementation(project(":detekt-rules"))
     implementation(project(":detekt-rules-empty"))
     implementation(project(":detekt-formatting"))
+    implementation(project(":detekt-cli"))
     implementation("com.beust:jcommander")
 
     testImplementation(project(":detekt-test-utils"))
@@ -17,6 +18,7 @@ dependencies {
 
 val documentationDir = "${rootProject.rootDir}/docs/pages/documentation"
 val configDir = "${rootProject.rootDir}/detekt-core/src/main/resources"
+val cliOptionsFile = "${rootProject.rootDir}/docs/pages/gettingstarted/cli-options.md"
 val defaultConfigFile = "$configDir/default-detekt-config.yml"
 
 val ruleModules = rootProject.subprojects
@@ -38,7 +40,9 @@ val generateDocumentation by tasks.registering {
 
     outputs.files(
         fileTree(documentationDir),
-        file(defaultConfigFile))
+        file(defaultConfigFile),
+        file(cliOptionsFile)
+    )
 
     doLast {
         javaexec {
@@ -54,7 +58,10 @@ val generateDocumentation by tasks.registering {
                 "--documentation",
                 documentationDir,
                 "--config",
-                configDir)
+                configDir,
+                "--cli-options",
+                cliOptionsFile
+            )
         }
     }
 }

detekt-generator/src/main/kotlin/io/gitlab/arturbosch/detekt/generator/Generator.kt

@@ -2,6 +2,7 @@ package io.gitlab.arturbosch.detekt.generator
 
 import io.github.detekt.parser.KtCompiler
 import io.gitlab.arturbosch.detekt.generator.collection.DetektCollector
+import io.gitlab.arturbosch.detekt.generator.printer.CliOptionsPrinter
 import io.gitlab.arturbosch.detekt.generator.printer.DetektPrinter
 import org.jetbrains.kotlin.psi.KtFile
 import java.io.PrintStream
@@ -16,6 +17,7 @@ class Generator(
 ) {
     private val collector = DetektCollector()
     private val printer = DetektPrinter(arguments)
+    private val cliOptionsPrinter = CliOptionsPrinter()
 
     private fun parseAll(parser: KtCompiler, root: Path): Collection<KtFile> =
         Files.walk(root)
@@ -32,6 +34,8 @@ class Generator(
             ktFiles.forEach(collector::visit)
 
             printer.print(collector.items)
+
+            cliOptionsPrinter.print(arguments.cliOptionsPath)
         }
 
         outPrinter.println("\nGenerated all detekt documentation in $time ms.")

detekt-generator/src/main/kotlin/io/gitlab/arturbosch/detekt/generator/GeneratorArgs.kt

@@ -22,6 +22,11 @@ class GeneratorArgs {
         description = "Output path for generated detekt config.")
     private var config: String? = null
 
+    @Parameter(names = ["--cli-options"],
+        required = true,
+        description = "Output path for generated cli options page.")
+    private var cliOptions: String? = null
+
     @Parameter(names = ["--help", "-h"],
         help = true, description = "Shows the usage.")
     var help: Boolean = false
@@ -42,4 +47,9 @@ class GeneratorArgs {
 
     val configPath: Path
         get() = Paths.get(checkNotNull(config) { "Configuration output path was not initialized by jcommander!" })
+
+    val cliOptionsPath: Path
+        get() = Paths.get(checkNotNull(cliOptions) {
+            "Cli options output path was not initialized by jcommander!"
+        })
 }

detekt-generator/src/main/kotlin/io/gitlab/arturbosch/detekt/generator/out/AbstractWriter.kt

@@ -9,9 +9,13 @@ internal abstract class AbstractWriter {
 
     fun write(path: Path, fileName: String, content: () -> String) {
         val filePath = path.resolve("$fileName.$ending")
-        filePath.parent?.let { Files.createDirectories(it) }
+        filePath.parent?.let { parentPath ->
+            if (!Files.exists(parentPath)) {
+                Files.createDirectories(parentPath)
+            }
+        }
         Files.write(filePath, content().toByteArray())
-        println("Wrote: $fileName.$ending")
+        println("Wrote: $filePath")
     }
 }
 

detekt-generator/src/main/kotlin/io/gitlab/arturbosch/detekt/generator/printer/CliOptionsPrinter.kt

@@ -0,0 +1,23 @@
+package io.gitlab.arturbosch.detekt.generator.printer
+
+import com.beust.jcommander.JCommander
+import io.gitlab.arturbosch.detekt.cli.CliArgs
+import java.nio.file.Files
+import java.nio.file.Path
+
+class CliOptionsPrinter {
+
+    private val jCommander = JCommander(CliArgs()).apply {
+        programName = "detekt"
+    }
+
+    fun print(filePath: Path) {
+        Files.write(filePath,
+            buildString {
+                appendLine("```")
+                jCommander.usageFormatter.usage(this)
+                appendLine("```")
+            }.toByteArray()
+        )
+    }
+}

detekt-generator/src/test/kotlin/io/gitlab/arturbosch/detekt/generator/printer/CliOptionsPrinterSpec.kt

@@ -0,0 +1,21 @@
+package io.gitlab.arturbosch.detekt.generator.printer
+
+import io.github.detekt.test.utils.createTempFileForTest
+import org.assertj.core.api.Assertions.assertThat
+import org.spekframework.spek2.Spek
+import org.spekframework.spek2.style.specification.describe
+
+class CliOptionsPrinterSpec : Spek({
+
+    describe("Cli Options Printer") {
+
+        it("prints the correct cli-options.md") {
+            val cliOptionsFile = createTempFileForTest("cli-options", ".md")
+            CliOptionsPrinter().print(cliOptionsFile.toAbsolutePath())
+            val markdownString = cliOptionsFile.toFile().readText()
+
+            assertThat(markdownString).contains("Usage: detekt [options]")
+            assertThat(markdownString).contains("--input, -i")
+        }
+    }
+})

docs/pages/gettingstarted/cli.md

@@ -37,90 +37,5 @@ detekt will exit with one of the following exit codes:
 
 The following parameters are shown when `--help` is entered.
 
-```
-Usage: detekt [options]
-  Options:
-    --auto-correct, -ac
-      Allow rules to auto correct code if they support it. The default rule
-      sets do NOT support auto correcting and won't change any line in the
-      users code base. However custom rules can be written to support auto
-      correcting. The additional 'formatting' rule set, added with
-      '--plugins', does support it and needs this flag.
-      Default: false
-    --baseline, -b
-      If a baseline xml file is passed in, only new code smells not in the
-      baseline are printed in the console.
-    --build-upon-default-config
-      Preconfigures detekt with a bunch of rules and some opinionated defaults
-      for you. Allows additional provided configurations to override the
-      defaults.
-      Default: false
-    --classpath, -cp
-      EXPERIMENTAL: Paths where to find user class files and depending jar
-      files. Used for type resolution.
-    --config, -c
-      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.
-      Default: false
-    --debug
-      Prints extra information about configurations and extensions.
-      Default: false
-    --disable-default-rulesets, -dd
-      Disables default rule sets.
-      Default: false
-    --excludes, -ex
-      Globing patterns describing paths to exclude from the analysis.
-    --fail-fast
-      Same as 'build-upon-default-config' but explicitly running all available
-      rules. With this setting only exit code 0 is returned when the analysis
-      does not find a single code smell. Additional configuration files can
-      override rule properties which includes turning off specific rules.
-      Default: false
-    --generate-config, -gc
-      Export default config. Path can be specified with --config option
-      (default path: default-detekt-config.yml)
-      Default: false
-    --help, -h
-      Shows the usage.
-    --includes, -in
-      Globing patterns describing paths to include in the analysis. Useful in
-      combination with 'excludes' patterns.
-    --input, -i
-      Input paths to analyze. Multiple paths are separated by comma. If not
-      specified the current working directory is used.
-    --jvm-target
-      EXPERIMENTAL: Target version of the generated JVM bytecode that was
-      generated during compilation and is now being used for type resolution
-      (1.6, 1.8, 9, 10, 11 or 12)
-      Default: JVM_1_6
-      Possible Values: [JVM_1_6, JVM_1_8, JVM_9, JVM_10, JVM_11, JVM_12, JVM_13]
-    --language-version
-      EXPERIMENTAL: Compatibility mode for Kotlin language version X.Y,
-      reports errors for all language features that came out later (1.0, 1.1,
-      1.2, 1.3, 1.4)
-      Possible Values: [1.0, 1.1, 1.2, 1.3, 1.4]
-    --parallel
-      Enables parallel compilation and analysis of source files. Do some
-      benchmarks first before enabling this flag. Heuristics show performance
-      benefits starting from 2000 lines of Kotlin code.
-      Default: false
-    --plugins, -p
-      Extra paths to plugin jars separated by ',' or ';'.
-    --report, -r
-      Generates a report for given 'report-id' and stores it on given 'path'.
-      Entry should consist of: [report-id:path]. Available 'report-id' values:
-      'txt', 'xml', 'html'. These can also be used in combination with each
-      other e.g. '-r txt:reports/detekt.txt -r xml:reports/detekt.xml'
-    --base-path, -bp
-      Specifies a directory as the base path.
-      Currently it impacts all file paths in the formatted reports.
-      File paths in console output and txt report are not affected and remain as absolute paths.
-    --version
-      Prints the detekt CLI version.
-      Default: false
-```
+{% include_relative cli-options.md %}
+