switches argument to --style, defaulting to github flavored markdown, and accepting as 'docc' as an alternative

Author: heckj

Sources/ArgumentParserTestHelpers/TestHelpers.swift

@@ -525,7 +525,7 @@ extension XCTest {
       command = [
         "generate-docc-reference", commandURL.path,
         "--output-directory", "-",
-        "--docc-flavored", "true",
+        "--style", "docc",
       ]
     } else {
       command = [

Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift

@@ -37,12 +37,12 @@ extension CommandInfoV0 {
   /// Recursively parses a command to generate markdown content that describes the command.
   /// - Parameters:
   ///   - path: The path of subcommands from the root command.
-  ///   - doccFlavored: a Boolean value that indicates whether to use docc-flavored markdown.
+  ///   - markdownStyle: The flavor of markdown to emit, either `docc` or `github`
   /// - Returns: A multi-line markdown file that describes the command.
   ///
   /// If `path` is empty, it represents a top-level command.
   /// Otherwise it's a subcommand, potentially recursive to multiple levels.
-  func toMarkdown(_ path: [String], doccFlavored: Bool) -> String {
+  func toMarkdown(_ path: [String], markdownStyle: OutputStyle) -> String {
     var result =
       String(repeating: "#", count: path.count + 1)
       + " \(self.doccReferenceTitle)\n\n"
@@ -72,11 +72,13 @@ extension CommandInfoV0 {
           continue
         }
 
-        if doccFlavored {
+        switch markdownStyle {
+        case .docc:
           result += "- term **\(arg.identity()):**\n\n"
-        } else {
+        case .github:
           result += "**\(arg.identity()):**\n\n"
         }
+
         if let abstract = arg.abstract {
           result += "*\(abstract)*\n\n"
         }
@@ -90,7 +92,7 @@ extension CommandInfoV0 {
     for subcommand in self.subcommands ?? [] {
       result +=
         subcommand.toMarkdown(
-          path + [self.commandName], doccFlavored: doccFlavored) + "\n\n"
+          path + [self.commandName], markdownStyle: markdownStyle) + "\n\n"
     }
 
     return result

Tools/generate-docc-reference/GenerateDoccReference.swift

@@ -36,6 +36,14 @@ extension GenerateDoccReferenceError: CustomStringConvertible {
   }
 }
 
+/// The flavor of generated markdown to emit.
+enum OutputStyle: String, EnumerableFlag, ExpressibleByArgument {
+  /// DocC-supported markdown
+  case docc
+  /// GitHub-flavored markdown
+  case github
+}
+
 @main
 struct GenerateDoccReference: ParsableCommand {
   static let configuration = CommandConfiguration(
@@ -53,7 +61,7 @@ struct GenerateDoccReference: ParsableCommand {
   @Option(
     name: .shortAndLong,
     help: "Use docc flavored markdown for the generated output.")
-  var doccFlavored: Bool = false
+  var style: OutputStyle = .github
 
   func validate() throws {
     if outputDirectory != "-" {
@@ -112,12 +120,12 @@ struct GenerateDoccReference: ParsableCommand {
     do {
       if self.outputDirectory == "-" {
         try self.generatePages(
-          from: toolInfo.command, savingTo: nil, doccFlavored: doccFlavored)
+          from: toolInfo.command, savingTo: nil, flavor: style)
       } else {
         try self.generatePages(
           from: toolInfo.command,
           savingTo: URL(fileURLWithPath: outputDirectory),
-          doccFlavored: doccFlavored)
+          flavor: style)
       }
     } catch {
       throw GenerateDoccReferenceError.failedToGenerateDoccReference(
@@ -129,14 +137,14 @@ struct GenerateDoccReference: ParsableCommand {
   /// - Parameters:
   ///   - command: The command to parse into a markdown output.
   ///   - directory: The directory to save the generated markdown file, printing it if `nil`.
-  ///   - doccFlavored: A Boolean value the indicates whether to generate docc-flavored markdown.
+  ///   - flavor: The flavor of markdown to use when generating the content.
   /// - Throws: An error if the markdown file cannot be generated or saved.
   func generatePages(
-    from command: CommandInfoV0, savingTo directory: URL?, doccFlavored: Bool
+    from command: CommandInfoV0, savingTo directory: URL?, flavor: OutputStyle
   )
     throws
   {
-    let page = command.toMarkdown([], doccFlavored: doccFlavored)
+    let page = command.toMarkdown([], markdownStyle: style)
 
     if let directory = directory {
       let fileName = command.doccReferenceFileName