Repository: apple/swift-argument-parser
Pull request #472 (2022-08-25 07:39:38)

Default to single page manuals
- Changes the generate-manual --single-page argument to --multi-page, so
  generate-manual will create a single manual page with all subcommand
  information by default instead of many distinct files.

rauhul: @swift-ci please test
rauhul: @swift-ci please test

rauhul: @swift-ci please test

Patch:
diff --git a/Tools/generate-manual/DSL/Document.swift b/Tools/generate-manual/DSL/Document.swift
index dfb0514..fe80d42 100644
--- a/Tools/generate-manual/DSL/Document.swift
+++ b/Tools/generate-manual/DSL/Document.swift
@@ -14,7 +14,7 @@ import ArgumentParserToolInfo
 import Foundation
 
 struct Document: MDocComponent {
-  var singlePage: Bool
+  var multiPage: Bool
   var date: Date
   var section: Int
   var authors: [AuthorArgument]
@@ -24,13 +24,13 @@ struct Document: MDocComponent {
     Preamble(date: date, section: section, command: command)
     Name(command: command)
     Synopsis(command: command)
-    if singlePage {
-      SinglePageDescription(command: command)
-    } else {
+    if multiPage {
       MultiPageDescription(command: command)
+    } else {
+      SinglePageDescription(command: command)
     }
     Exit(section: section)
-    if !singlePage {
+    if multiPage {
       SeeAlso(section: section, command: command)
     }
     Authors(authors: authors)
diff --git a/Tools/generate-manual/GenerateManual.swift b/Tools/generate-manual/GenerateManual.swift
index 0520c0f..55bdaaa 100644
--- a/Tools/generate-manual/GenerateManual.swift
+++ b/Tools/generate-manual/GenerateManual.swift
@@ -29,8 +29,8 @@ struct GenerateManual: ParsableCommand {
   @Argument(help: "Tool to generate manual for.")
   var tool: String
 
-  @Flag(help: "Generate a single page with information for all subcommands.")
-  var singlePage = false
+  @Flag(help: "Generate a separate manual for each subcommand.")
+  var multiPage = false
 
   @Option(name: .long, help: "Override the creation date of the manual. Format: 'yyyy-mm-dd'.")
   var date: Date = Date()
@@ -46,7 +46,7 @@ struct GenerateManual: ParsableCommand {
 
   func validate() throws {
     // Only man pages 1 through 9 are valid.
-    if !(1...9).contains(section) {
+    guard (1...9).contains(section) else {
       throw ValidationError("Invalid manual section passed to --section")
     }
 
@@ -106,7 +106,7 @@ struct GenerateManual: ParsableCommand {
 
   func generatePages(from command: CommandInfoV0, savingTo directory: URL?) throws {
     let document = Document(
-      singlePage: singlePage,
+      multiPage: multiPage,
       date: date,
       section: section,
       authors: authors,
@@ -121,7 +121,7 @@ struct GenerateManual: ParsableCommand {
       print(page)
     }
 
-    if !singlePage {
+    if multiPage {
       for subcommand in command.subcommands ?? [] {
         try generatePages(from: subcommand, savingTo: directory)
       }


Test patch:
diff --git a/Sources/ArgumentParserTestHelpers/TestHelpers.swift b/Sources/ArgumentParserTestHelpers/TestHelpers.swift
index d0ccb05..8fcd181 100644
--- a/Sources/ArgumentParserTestHelpers/TestHelpers.swift
+++ b/Sources/ArgumentParserTestHelpers/TestHelpers.swift
@@ -325,7 +325,7 @@ extension XCTest {
   }
 
   public func AssertGenerateManual(
-    singlePage: Bool,
+    multiPage: Bool,
     command: String,
     expected: String,
     file: StaticString = #file,
@@ -341,8 +341,8 @@ extension XCTest {
       "--authors", "The Appleseeds<appleseeds@apple.com>",
       "--output-directory", "-",
     ]
-    if singlePage {
-      command.append("--single-page")
+    if multiPage {
+      command.append("--multi-page")
     }
     try AssertExecuteCommand(
       command: command,
diff --git a/Tests/ArgumentParserGenerateManualTests/CountLinesGenerateManualTests.swift b/Tests/ArgumentParserGenerateManualTests/CountLinesGenerateManualTests.swift
index 3e6e66d..2ef4608 100644
--- a/Tests/ArgumentParserGenerateManualTests/CountLinesGenerateManualTests.swift
+++ b/Tests/ArgumentParserGenerateManualTests/CountLinesGenerateManualTests.swift
@@ -17,7 +17,7 @@ import ArgumentParserTestHelpers
 final class CountLinesGenerateManualTests: XCTestCase {
   func testCountLines_SinglePageManual() throws {
     guard #available(macOS 12, *) else { return }
-    try AssertGenerateManual(singlePage: true, command: "count-lines", expected: #"""
+    try AssertGenerateManual(multiPage: false, command: "count-lines", expected: #"""
       .\" "Generated by swift-argument-parser"
       .Dd May 12, 1996
       .Dt COUNT-LINES 9
@@ -59,7 +59,7 @@ final class CountLinesGenerateManualTests: XCTestCase {
   
   func testCountLines_MultiPageManual() throws {
     guard #available(macOS 12, *) else { return }
-    try AssertGenerateManual(singlePage: false, command: "count-lines", expected: #"""
+    try AssertGenerateManual(multiPage: true, command: "count-lines", expected: #"""
       .\" "Generated by swift-argument-parser"
       .Dd May 12, 1996
       .Dt COUNT-LINES 9
diff --git a/Tests/ArgumentParserGenerateManualTests/MathGenerateManualTests.swift b/Tests/ArgumentParserGenerateManualTests/MathGenerateManualTests.swift
index 14fa3c6..fb49217 100644
--- a/Tests/ArgumentParserGenerateManualTests/MathGenerateManualTests.swift
+++ b/Tests/ArgumentParserGenerateManualTests/MathGenerateManualTests.swift
@@ -15,7 +15,7 @@ import ArgumentParserTestHelpers
 
 final class MathGenerateManualTests: XCTestCase {
   func testMath_SinglePageManual() throws {
-    try AssertGenerateManual(singlePage: true, command: "math", expected: #"""
+    try AssertGenerateManual(multiPage: false, command: "math", expected: #"""
       .\" "Generated by swift-argument-parser"
       .Dd May 12, 1996
       .Dt MATH 9
@@ -120,7 +120,7 @@ final class MathGenerateManualTests: XCTestCase {
   }
 
   func testMath_MultiPageManual() throws {
-    try AssertGenerateManual(singlePage: false, command: "math", expected: #"""
+    try AssertGenerateManual(multiPage: true, command: "math", expected: #"""
       .\" "Generated by swift-argument-parser"
       .Dd May 12, 1996
       .Dt MATH 9
diff --git a/Tests/ArgumentParserGenerateManualTests/RepeatGenerateManualTests.swift b/Tests/ArgumentParserGenerateManualTests/RepeatGenerateManualTests.swift
index fc772f6..7a879a3 100644
--- a/Tests/ArgumentParserGenerateManualTests/RepeatGenerateManualTests.swift
+++ b/Tests/ArgumentParserGenerateManualTests/RepeatGenerateManualTests.swift
@@ -14,7 +14,7 @@ import ArgumentParserTestHelpers
 
 final class RepeatGenerateManualTests: XCTestCase {
   func testMath_SinglePageManual() throws {
-    try AssertGenerateManual(singlePage: true, command: "repeat", expected: #"""
+    try AssertGenerateManual(multiPage: false, command: "repeat", expected: #"""
       .\" "Generated by swift-argument-parser"
       .Dd May 12, 1996
       .Dt REPEAT 9
@@ -55,7 +55,7 @@ final class RepeatGenerateManualTests: XCTestCase {
   }
 
   func testMath_MultiPageManual() throws {
-    try AssertGenerateManual(singlePage: false, command: "repeat", expected: #"""
+    try AssertGenerateManual(multiPage: true, command: "repeat", expected: #"""
       .\" "Generated by swift-argument-parser"
       .Dd May 12, 1996
       .Dt REPEAT 9
diff --git a/Tests/ArgumentParserGenerateManualTests/RollDiceGenerateManualTests.swift b/Tests/ArgumentParserGenerateManualTests/RollDiceGenerateManualTests.swift
index b07c354..ecdc5ec 100644
--- a/Tests/ArgumentParserGenerateManualTests/RollDiceGenerateManualTests.swift
+++ b/Tests/ArgumentParserGenerateManualTests/RollDiceGenerateManualTests.swift
@@ -14,7 +14,7 @@ import ArgumentParserTestHelpers
 
 final class RollDiceGenerateManualTests: XCTestCase {
   func testRollDice_SinglePageManual() throws {
-    try AssertGenerateManual(singlePage: true, command: "roll", expected: #"""
+    try AssertGenerateManual(multiPage: false, command: "roll", expected: #"""
       .\" "Generated by swift-argument-parser"
       .Dd May 12, 1996
       .Dt ROLL 9
@@ -60,7 +60,7 @@ final class RollDiceGenerateManualTests: XCTestCase {
   }
 
   func testRollDice_MultiPageManual() throws {
-    try AssertGenerateManual(singlePage: false, command: "roll", expected: #"""
+    try AssertGenerateManual(multiPage: true, command: "roll", expected: #"""
       .\" "Generated by swift-argument-parser"
       .Dd May 12, 1996
       .Dt ROLL 9