markdown support in cli help

Author: HT154

docs/modules/pkl-cli/pages/index.adoc

@@ -919,6 +919,7 @@ Commands are defined by creating a module that extends `pkl:Command`:
 .my-tool.pkl
 ----
 /// This doc comment becomes part of the command's CLI help!
+/// Markdown formatting is **allowed!**
 extends "pkl:Command"
 
 options: Options
@@ -951,6 +952,7 @@ If additional functionality is desired, xref:language-reference:index.adoc#exter
 Each property of the class of a command's `options` property becomes a command line option.
 Properties with the `local`, `hidden`, `fixed`, and/or `const` modifiers are not parsed as options
 A property's doc comment, if present, becomes the corresponding option's CLI help description.
+Doc comments are interpreted as Markdown text and formatted nicely when displayed to users.
 Properties must have xref:language-reference:index.adoc#type-annotations[type annotations] to determine how they are parsed.
 
 Properties may be xref:language-reference:index.adoc#annotations[annotated] to influence how they behave:

pkl-cli/src/main/kotlin/org/pkl/cli/CliCommandRunner.kt

@@ -29,6 +29,7 @@ import kotlin.io.path.writeBytes
 import org.pkl.commons.cli.CliBaseOptions
 import org.pkl.commons.cli.CliCommand
 import org.pkl.commons.cli.CliException
+import org.pkl.commons.cli.commands.installCommonOptions
 import org.pkl.commons.currentWorkingDir
 import org.pkl.core.Closeables
 import org.pkl.core.CommandSpec
@@ -65,6 +66,7 @@ constructor(
       evaluator.evaluateCommand(uri(normalizedSourceModule)) { spec ->
         try {
           val root = SynthesizedRunCommand(spec, this, options.sourceModules.first().toString())
+          root.installCommonOptions(includeVersion = false)
           root.subcommands(
             CompletionCommand(
               name = "shell-completion",

pkl-cli/src/test/kotlin/org/pkl/cli/CliCommandRunnerTest.kt

@@ -17,6 +17,7 @@ package org.pkl.cli
 
 import com.github.ajalt.clikt.core.CliktError
 import com.github.ajalt.clikt.core.MissingOption
+import com.github.ajalt.clikt.core.PrintHelpMessage
 import com.github.tomakehurst.wiremock.junit5.WireMockTest
 import java.io.ByteArrayOutputStream
 import java.net.URI

pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/commands/extensions.kt

@@ -27,14 +27,16 @@ import org.pkl.core.Release
 
 private val theme = Theme { styles["markdown.code.span"] = TextStyle(bold = true) }
 
-fun <T : BaseCliktCommand<T>> T.installCommonOptions() {
+fun <T : BaseCliktCommand<T>> T.installCommonOptions(includeVersion: Boolean = true) {
   installMordantMarkdown()
 
-  versionOption(
-    Release.current().versionInfo,
-    names = setOf("-v", "--version"),
-    message = { if (commandName == "pkl") it else it.replaceFirst("Pkl", commandName) },
-  )
+  if (includeVersion) {
+    versionOption(
+      Release.current().versionInfo,
+      names = setOf("-v", "--version"),
+      message = { if (commandName == "pkl") it else it.replaceFirst("Pkl", commandName) },
+    )
+  }
 
   context { terminal = Terminal(theme = theme) }
 }