Fix reference docs generation to include sections for options referenced elsewhere in the docs, even if they are internal or empty

Author: Gedochao

modules/generate-reference-doc/src/main/scala/scala/cli/doc/GenerateReferenceDoc.scala

@@ -144,6 +144,9 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
           (k, v.map(_._2).distinct.sortBy(_.name))
       }
 
+    // Collect all origins that are referenced by commands, even if they have no args
+    val allReferencedOrigins = commandOriginsMap.keySet ++ argsByOrigin.keySet
+
     val mainOptionsContent   = new StringBuilder
     val hiddenOptionsContent = new StringBuilder
 
@@ -167,13 +170,15 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
 
     mainOptionsContent.section(scalacOptionForwarding)
 
-    for ((origin, originArgs) <- argsByOrigin.toVector.sortBy(_._1)) {
+    for (origin <- allReferencedOrigins.toVector.sortBy(identity)) {
+      val originArgs            = argsByOrigin.getOrElse(origin, Nil)
       val distinctArgs          = originArgs.map(_.withOrigin(None)).distinct
       val originCommands        = commandOriginsMap.getOrElse(origin, Nil)
       val onlyForHiddenCommands = originCommands.nonEmpty && originCommands.forall(_.hidden)
-      val allArgsHidden         = distinctArgs.forall(_.noHelp)
-      val isInternal            = onlyForHiddenCommands || allArgsHidden
-      val b                     = if (isInternal) hiddenOptionsContent else mainOptionsContent
+      // Empty option groups should not be treated as internal if they're referenced by commands
+      val allArgsHidden = distinctArgs.nonEmpty && distinctArgs.forall(_.noHelp)
+      val isInternal    = onlyForHiddenCommands || allArgsHidden
+      val b             = if (isInternal) hiddenOptionsContent else mainOptionsContent
       if (originCommands.nonEmpty) {
         val formattedOrigin   = formatOrigin(origin)
         val formattedCommands = originCommands.map { c =>
@@ -194,35 +199,41 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
              |""".stripMargin
         )
 
-        for (arg <- distinctArgs) {
-          import caseapp.core.util.NameOps._
-          arg.name.option(nameFormatter)
-          val names = (arg.name +: arg.extraNames).map(_.option(nameFormatter))
-          b.append(s"### `${names.head}`\n\n")
-          if (names.tail.nonEmpty)
-            b.append(
-              names
-                .tail
-                .sortBy(_.dropWhile(_ == '-'))
-                .map {
-                  case name if arg.deprecatedOptionAliases.contains(name) =>
-                    s"[deprecated] `$name`"
-                  case name => s"`$name`"
-                }
-                .mkString("Aliases: ", ", ", "\n\n")
-            )
-
-          if (onlyRestricted)
-            b.section(s"`${arg.level.md}` per Scala Runner specification")
-          else if (isInternal || arg.noHelp) b.append("[Internal]\n")
-
-          for (desc <- arg.helpMessage.map(_.referenceDocMessage))
-            b.append(
-              s"""$desc
-                 |
-                 |""".stripMargin
-            )
-        }
+        if (distinctArgs.nonEmpty)
+          for (arg <- distinctArgs) {
+            import caseapp.core.util.NameOps._
+            arg.name.option(nameFormatter)
+            val names = (arg.name +: arg.extraNames).map(_.option(nameFormatter))
+            b.append(s"### `${names.head}`\n\n")
+            if (names.tail.nonEmpty)
+              b.append(
+                names
+                  .tail
+                  .sortBy(_.dropWhile(_ == '-'))
+                  .map {
+                    case name if arg.deprecatedOptionAliases.contains(name) =>
+                      s"[deprecated] `$name`"
+                    case name => s"`$name`"
+                  }
+                  .mkString("Aliases: ", ", ", "\n\n")
+              )
+
+            if (onlyRestricted)
+              b.section(s"`${arg.level.md}` per Scala Runner specification")
+            else if (isInternal || arg.noHelp) b.append("[Internal]\n")
+
+            for (desc <- arg.helpMessage.map(_.referenceDocMessage))
+              b.append(
+                s"""$desc
+                   |
+                   |""".stripMargin
+              )
+          }
+        else
+          // Empty option group - add a note
+          b.append(
+            "*This section was automatically generated and may be empty if no options were available.*\n\n"
+          )
       }
     }
 

website/docs/reference/scala-command/cli-options.md

@@ -42,6 +42,16 @@ are assumed to be Scala compiler options and will be propagated to Scala Compile
 
 
 
+## Benchmarking options
+
+Available in commands:
+
+[`bsp`](./commands.md#bsp), [`compile`](./commands.md#compile), [`doc`](./commands.md#doc), [`fmt` , `format` , `scalafmt`](./commands.md#fmt), [`repl` , `console`](./commands.md#repl), [`run`](./commands.md#run), [`setup-ide`](./commands.md#setup-ide), [`shebang`](./commands.md#shebang), [`test`](./commands.md#test)
+
+<!-- Automatically generated, DO NOT EDIT MANUALLY -->
+
+*This section was automatically generated and may be empty if no options were available.*
+
 ## Compilation server options
 
 Available in commands:
@@ -186,6 +196,16 @@ Aliases: `-f`
 
 Force overwriting values for key
 
+## Cross options
+
+Available in commands:
+
+[`compile`](./commands.md#compile), [`repl` , `console`](./commands.md#repl), [`run`](./commands.md#run), [`shebang`](./commands.md#shebang), [`test`](./commands.md#test)
+
+<!-- Automatically generated, DO NOT EDIT MANUALLY -->
+
+*This section was automatically generated and may be empty if no options were available.*
+
 ## Debug options
 
 Available in commands:
@@ -664,6 +684,26 @@ Aliases: `--list-main-class`, `--list-main-classes`, `--list-main-method`, `--li
 
 List main classes available in the current context
 
+## Markdown options
+
+Available in commands:
+
+[`bsp`](./commands.md#bsp), [`compile`](./commands.md#compile), [`doc`](./commands.md#doc), [`fmt` , `format` , `scalafmt`](./commands.md#fmt), [`repl` , `console`](./commands.md#repl), [`run`](./commands.md#run), [`setup-ide`](./commands.md#setup-ide), [`shebang`](./commands.md#shebang), [`test`](./commands.md#test)
+
+<!-- Automatically generated, DO NOT EDIT MANUALLY -->
+
+*This section was automatically generated and may be empty if no options were available.*
+
+## Pgp scala signing options
+
+Available in commands:
+
+[`config`](./commands.md#config)
+
+<!-- Automatically generated, DO NOT EDIT MANUALLY -->
+
+*This section was automatically generated and may be empty if no options were available.*
+
 ## Power options
 
 Available in commands:
@@ -678,6 +718,16 @@ Available in commands:
 
 Allows to use restricted & experimental features
 
+## Python options
+
+Available in commands:
+
+[`bsp`](./commands.md#bsp), [`compile`](./commands.md#compile), [`doc`](./commands.md#doc), [`fmt` , `format` , `scalafmt`](./commands.md#fmt), [`repl` , `console`](./commands.md#repl), [`run`](./commands.md#run), [`setup-ide`](./commands.md#setup-ide), [`shebang`](./commands.md#shebang), [`test`](./commands.md#test)
+
+<!-- Automatically generated, DO NOT EDIT MANUALLY -->
+
+*This section was automatically generated and may be empty if no options were available.*
+
 ## Run options
 
 Available in commands:
@@ -1160,6 +1210,16 @@ Allows to execute a passed string as Java code
 
 A synonym to --scala-snippet, which defaults the sub-command to `run` when no sub-command is passed explicitly
 
+## Source generator options
+
+Available in commands:
+
+[`bsp`](./commands.md#bsp), [`compile`](./commands.md#compile), [`doc`](./commands.md#doc), [`fmt` , `format` , `scalafmt`](./commands.md#fmt), [`repl` , `console`](./commands.md#repl), [`run`](./commands.md#run), [`setup-ide`](./commands.md#setup-ide), [`shebang`](./commands.md#shebang), [`test`](./commands.md#test)
+
+<!-- Automatically generated, DO NOT EDIT MANUALLY -->
+
+*This section was automatically generated and may be empty if no options were available.*
+
 ## Suppress warning options
 
 Available in commands: