Tweak reference doc generated messages

- use `detailedMessage` instead of `message` for commands - convert console keys to markdown fence code blocks - filter out console keys from reference docs
VirtusLab · Feb 24, 2023 · 580bece · 580bece
1 parent 0b8c70f
commit 580bece
Show file tree

Hide file tree

Showing 7 changed files with 481 additions and 153 deletions.
diff --git a/modules/cli/src/main/scala/scala/cli/commands/config/ConfigOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/config/ConfigOptions.scala
@@ -96,9 +96,9 @@ object ConfigOptions {
     s"""$helpHeader
        |
        |Syntax:
-       |  $progName $cmdName key value
+       |  ${Console.BOLD}$progName $cmdName key value${Console.RESET}
        |For example, to globally set the interactive mode:
-       |  $progName $cmdName interactive true
+       |  ${Console.BOLD}$progName $cmdName interactive true${Console.RESET}
        |
        |${HelpMessages.commandDocWebsiteReference(websiteSuffix)}""".stripMargin
 }
diff --git a/modules/cli/src/main/scala/scala/cli/commands/shebang/ShebangOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/shebang/ShebangOptions.scala
@@ -2,6 +2,7 @@ package scala.cli.commands.shebang
 
 import caseapp.*
 
+import scala.build.internal.util.ConsoleUtils.ScalaCliConsole
 import scala.cli.ScalaCli.{baseRunnerName, fullRunnerName, progName}
 import scala.cli.commands.run.RunOptions
 import scala.cli.commands.shared.{HasSharedOptions, HelpMessages, SharedOptions}
@@ -30,23 +31,16 @@ object ShebangOptions {
        |
        |When relying on the `run` sub-command, inputs and $baseRunnerName options can be mixed,
        |while program args have to be specified after `--`
-       |
-       |```sh
-       |$progName [command] [${baseRunnerName}_options | input]... -- [program_arguments]...
-       |```
+       |  ${Console.BOLD}$progName [command] [${baseRunnerName}_options | input]... -- [program_arguments]...${Console.RESET}
        |
        |However, for the `shebang` sub-command, only a single input file can be set, while all $baseRunnerName options
        |have to be set before the input file.
        |All inputs after the first are treated as program arguments, without the need for `--`
-       |```sh
-       |$progName shebang [${baseRunnerName}_options]... input [program_arguments]...
-       |```
+       |  ${Console.BOLD}$progName shebang [${baseRunnerName}_options]... input [program_arguments]...${Console.RESET}
        |
        |Using this, it is possible to conveniently set up Unix shebang scripts. For example:
-       |```sh
-       |#!/usr/bin/env -S $progName shebang --scala-version 2.13
-       |println("Hello, world")
-       |```
+       |  ${ScalaCliConsole.GRAY}#!/usr/bin/env -S $progName shebang --scala-version 2.13
+       |  println("Hello, world")${Console.RESET}
        |
        |${HelpMessages.commandDocWebsiteReference(cmdName)}""".stripMargin
 }
diff --git a/modules/generate-reference-doc/src/main/scala/scala/cli/doc/GenerateReferenceDoc.scala b/modules/generate-reference-doc/src/main/scala/scala/cli/doc/GenerateReferenceDoc.scala
@@ -293,7 +293,8 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
 
         if (command.names.tail.nonEmpty)
           b.section(command.names.map(_.mkString(" ")).tail.mkString("Aliases: `", "`, `", "`"))
-        for (desc <- command.messages.helpMessage.map(_.referenceDocMessage)) b.section(desc)
+        for (desc <- command.messages.helpMessage.map(_.referenceDocDetailedMessage))
+          b.section(desc)
         optionsForCommand(command)
         b.section("---")
       }
@@ -333,7 +334,7 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
       b.append(s"$headerPrefix## ${names.head}\n\n")
       if (names.tail.nonEmpty) b.append(names.tail.sorted.mkString("Aliases: `", "`, `", "`\n\n"))
 
-      for (desc <- c.messages.helpMessage.map(_.referenceDocMessage)) b.section(desc)
+      for (desc <- c.messages.helpMessage.map(_.referenceDocDetailedMessage)) b.section(desc)
 
       if (origins.nonEmpty) {
         val links = origins.map { origin =>

diff --git a/modules/generate-reference-doc/src/main/scala/scala/cli/doc/ReferenceDocUtils.scala b/modules/generate-reference-doc/src/main/scala/scala/cli/doc/ReferenceDocUtils.scala
@@ -2,11 +2,41 @@ package scala.cli.doc
 
 import caseapp.HelpMessage
 
-import scala.cli.commands.util.ConsoleUtils.*
+import java.util.stream.IntStream
+
+import scala.build.internal.util.ConsoleUtils.*
+import scala.jdk.StreamConverters.*
 
 object ReferenceDocUtils {
+  extension (s: String) {
+    def consoleToFence: String =
+      s
+        .lines()
+        .toScala(scala.List)
+        .fold("") { (acc, line) =>
+          val maybeOpenFence =
+            if line.contains(Console.BOLD) then
+              """```sh
+                |""".stripMargin
+            else if line.contains(ScalaCliConsole.GRAY) then
+              """```scala
+                |""".stripMargin
+            else ""
+          val maybeCloseFence =
+            if line.contains(Console.RESET) then
+              """
+                |```""".stripMargin
+            else ""
+          val newLine = s"$maybeOpenFence${line.noConsoleKeys}$maybeCloseFence"
+          if acc.isEmpty then newLine
+          else s"""$acc
+                  |$newLine""".stripMargin
+        }
+  }
   extension (helpMessage: HelpMessage) {
-    def referenceDocMessage: String = helpMessage.message.noConsoleKeys
+    def referenceDocMessage: String = helpMessage.message.consoleToFence.noConsoleKeys
+    def referenceDocDetailedMessage: String =
+      helpMessage.detailedMessage.consoleToFence.noConsoleKeys
   }
 
 }