Transform DocC archives for static hosting by default (#121) (#136)

Updates `docc convert` to transform for static hosting by default.

This keeps the original `--transform-for-static-hosting` flag for
backwards compatibility and adds a new
`--no-transform-for-static-hosting` flag to explicitly opt-out.

Resolves rdar://91173450.

Author: ethan-kusters

Sources/SwiftDocC/Infrastructure/Diagnostics/Diagnostic.swift

@@ -66,7 +66,15 @@ public struct Diagnostic: DescribedError {
     /// the second *X* while adding a note on the first *X* to note that it was the first occurrence.
     public var notes = [DiagnosticNote]()
 
-    public init(source: URL?, severity: DiagnosticSeverity, range: SourceRange?, identifier: String, summary: String, explanation: String? = nil, notes: [DiagnosticNote] = []) {
+    public init(
+        source: URL? = nil,
+        severity: DiagnosticSeverity,
+        range: SourceRange? = nil,
+        identifier: String,
+        summary: String,
+        explanation: String? = nil,
+        notes: [DiagnosticNote] = []
+    ) {
         self.source = source
         self.severity = severity
         self.range = range

Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift

@@ -238,9 +238,17 @@ extension Docc {
             return outputURL
         }
 
-        /// Defaults to false
-        @Flag(help: "Produce a Swift-DocC Archive that supports a static hosting environment.")
-        public var transformForStaticHosting = false
+        /// A Boolean value that is true if the DocC archive produced by this conversion
+        /// will support static hosting environments.
+        ///
+        /// This value defaults to true but can be explicitly disabled with the
+        /// `--no-transform-for-static-hosting` flag.
+        @Flag(
+            inversion: .prefixedNo,
+            exclusivity: .exclusive,
+            help: "Produce a DocC archive that supports static hosting environments."
+        )
+        public var transformForStaticHosting = true
 
         /// A user-provided relative path to be used in the archived output
         @Option(
@@ -251,6 +259,10 @@ extension Docc {
         )
         var hostingBasePath: String?
 
+        /// The file handle that should be used for emitting warnings during argument validation.
+        ///
+        /// Provided as a static variable to allow for redirecting output in unit tests.
+        static var _errorLogHandle: LogHandle = .standardError
 
         // MARK: - Property Validation
 
@@ -288,9 +300,29 @@ extension Docc {
                     }
 
                 } else {
-                    throw TemplateOption.missingHTMLTemplateError(
-                        path: templateOption.defaultTemplateURL.path
+                    let invalidOrMissingTemplateDiagnostic = Diagnostic(
+                        severity: .warning,
+                        identifier: "org.swift.docc.MissingHTMLTemplate",
+                        summary: "Invalid or missing HTML template directory",
+                        explanation: """
+                            Invalid or missing HTML template directory, relative to the docc \
+                            executable, at: '\(templateOption.defaultTemplateURL.path)'.
+                            Set the '\(TemplateOption.environmentVariableKey)' environment variable \
+                            to use a custom HTML template.
+                            
+                            Conversion will continue, but the produced DocC archive will not be \
+                            compatible with static hosting environments.
+                            
+                            Pass the '--no-transform-for-static-hosting' flag to silence this warning.
+                            """
+                    )
+                    
+                    print(
+                        invalidOrMissingTemplateDiagnostic.localizedDescription,
+                        to: &Self._errorLogHandle
                     )
+                    
+                    transformForStaticHosting = false
                 }
             }
 

Tests/SwiftDocCUtilitiesTests/ArgumentParsing/ConvertSubcommandTests.swift

@@ -20,6 +20,12 @@ class ConvertSubcommandTests: XCTestCase {
     private let testTemplateURL = Bundle.module.url(
         forResource: "Test Template", withExtension: nil, subdirectory: "Test Resources")!
 
+    override func setUp() {
+        // By default, send all warnings to `.none` instead of filling the
+        // test console output with unrelated messages.
+        Docc.Convert._errorLogHandle = .none
+    }
+    
     func testOptionsValidation() throws {
         // create source bundle directory
         let sourceURL = try createTemporaryDirectory(named: "documentation")
@@ -363,4 +369,72 @@ class ConvertSubcommandTests: XCTestCase {
         XCTAssertTrue(commandWithFlag.experimentalEnableCustomTemplates)
         XCTAssertTrue(actionWithFlag.experimentalEnableCustomTemplates)
     }
+    
+    func testTransformForStaticHostingFlagWithoutHTMLTemplate() throws {
+        unsetenv(TemplateOption.environmentVariableKey)
+        
+        // Since there's no custom template set (and relative HTML template lookup isn't
+        // supported in the test harness), we expect `transformForStaticHosting` to
+        // be false in every possible scenario of the flag, even when explicitly requested.
+        
+        do {
+            let convertOptions = try Docc.Convert.parse([
+                testBundleURL.path,
+            ])
+            
+            XCTAssertFalse(convertOptions.transformForStaticHosting)
+        }
+        
+        do {
+            let convertOptions = try Docc.Convert.parse([
+                testBundleURL.path,
+                "--transform-for-static-hosting",
+            ])
+            
+            XCTAssertFalse(convertOptions.transformForStaticHosting)
+        }
+        
+        do {
+            let convertOptions = try Docc.Convert.parse([
+                testBundleURL.path,
+                "--no-transform-for-static-hosting",
+            ])
+            
+            XCTAssertFalse(convertOptions.transformForStaticHosting)
+        }
+    }
+    
+    func testTransformForStaticHostingFlagWithHTMLTemplate() throws {
+        setenv(TemplateOption.environmentVariableKey, testTemplateURL.path, 1)
+        
+        // Since we've provided an HTML template, we expect `transformForStaticHosting`
+        // to be true by default, and when explicitly requested. It should only be false
+        // when `--no-transform-for-static-hosting` is passed.
+        
+        do {
+            let convertOptions = try Docc.Convert.parse([
+                testBundleURL.path,
+            ])
+            
+            XCTAssertTrue(convertOptions.transformForStaticHosting)
+        }
+        
+        do {
+            let convertOptions = try Docc.Convert.parse([
+                testBundleURL.path,
+                "--transform-for-static-hosting",
+            ])
+            
+            XCTAssertTrue(convertOptions.transformForStaticHosting)
+        }
+        
+        do {
+            let convertOptions = try Docc.Convert.parse([
+                testBundleURL.path,
+                "--no-transform-for-static-hosting",
+            ])
+            
+            XCTAssertFalse(convertOptions.transformForStaticHosting)
+        }
+    }
 }