Merge branch 'master' into mattt/commonmark-output-improvements

Author: mattt

Package.resolved

@@ -19,13 +19,15 @@ let package = Package(
         .package(url: "https://github.com/SwiftDocOrg/Markup.git", .upToNextMinor(from: "0.0.3")),
         .package(url: "https://github.com/NSHipster/SwiftSyntaxHighlighter.git", .revision("1.0.0")),
         .package(url: "https://github.com/apple/swift-argument-parser.git", .upToNextMinor(from: "0.0.2")),
+        .package(url: "https://github.com/apple/swift-log.git", .upToNextMinor(from: "1.2.0")),
+        .package(url: "https://github.com/NSHipster/swift-log-github-actions.git", .upToNextMinor(from: "0.0.1")),
     ],
     targets: [
         // Targets are the basic building blocks of a package. A target can define a module or a test suite.
         // Targets can depend on other targets in this package, and on products in packages which this package depends on.
         .target(
             name: "swift-doc",
-            dependencies: ["ArgumentParser", "SwiftDoc", "SwiftSemantics", "SwiftMarkup", "CommonMarkBuilder", "HypertextLiteral", "Markup", "DCOV", "GraphViz", "SwiftSyntaxHighlighter"]
+            dependencies: ["ArgumentParser", "SwiftDoc", "SwiftSemantics", "SwiftMarkup", "CommonMarkBuilder", "HypertextLiteral", "Markup", "DCOV", "GraphViz", "SwiftSyntaxHighlighter", "Logging", "LoggingGitHubActions"]
         ),
         .target(
             name: "DCOV",

Package.swift

@@ -44,12 +44,43 @@ $ make install
 
 ### Usage
 
-`swift-doc` takes one or more paths and enumerates them recursively,
+    OVERVIEW: A utility for generating documentation for Swift code.
+    
+    USAGE: swift-doc <subcommand>
+    
+    OPTIONS:
+      -h, --help              Show help information.
+    
+    SUBCOMMANDS:
+      generate                Generates Swift documentation
+      coverage                Generates documentation coverage statistics for Swift
+                              files
+      diagram                 Generates diagram of Swift symbol relationships
+
+#### swift-doc generate
+
+    OVERVIEW: Generates Swift documentation
+
+    USAGE: swift-doc generate [<inputs> ...] --module-name <module-name> [--output <output>] [--format <format>]
+
+    ARGUMENTS:
+      <inputs>                One or more paths to Swift files 
+
+    OPTIONS:
+      -n, --module-name <module-name>
+                              The name of the module 
+      -o, --output <output>   The path for generated output (default:
+                              .build/documentation)
+      -f, --format <format>   The output format (default: commonmark)
+      -h, --help              Show help information.
+
+The `generate` subcommand 
+takes one or more paths and enumerates them recursively,
 collecting all Swift files into a single "module"
 and generating documentation accordingly.
 
 ```terminal
-$ swift doc generate path/to/SwiftProject/Sources
+$ swift doc generate path/to/SwiftProject/Sources --module-name SwiftProject
 $ tree .build/documentation
 $ documentation/
 ├── Home
@@ -64,21 +95,32 @@ in CommonMark / GitHub Wiki format,
 but you can change that with the `--output` and `--format` option flags.
 
 ```terminal
-$ swift doc generate path/to/SwiftProject/Sources --output Documentation --format html
+$ swift doc generate path/to/SwiftProject/Sources --module-name SwiftProject --output Documentation --format html
 $ Documentation/
 ├── (...)
 └── index.html
 ```
 
 #### swift-doc coverage
 
+    OVERVIEW: Generates documentation coverage statistics for Swift files
+
+    USAGE: swift-doc coverage [<inputs> ...] [--output <output>]
+
+    ARGUMENTS:
+      <inputs>                One or more paths to Swift files 
+
+    OPTIONS:
+      -o, --output <output>   The path for generated report 
+      -h, --help              Show help information.
+
 The `coverage` subcommand
 generates documentation coverage statistics for Swift files.
 
 ```terminal
 $ git clone https://github.com/SwiftDocOrg/SwiftSemantics.git
 
-$ swift run swift-doc coverage SwiftSemantics/Sources/ --output "dcov.json"
+$ swift run swift-doc coverage SwiftSemantics/Sources --output "dcov.json"
 $ cat dcov.json | jq ".data.totals"
 {
   "count": 207,
@@ -110,6 +152,16 @@ please reach out by [opening an Issue][open an issue]!
 
 #### swift-doc diagram
 
+    OVERVIEW: Generates diagram of Swift symbol relationships
+
+    USAGE: swift-doc diagram [<inputs> ...]
+
+    ARGUMENTS:
+      <inputs>                One or more paths to Swift files 
+
+    OPTIONS:
+      -h, --help              Show help information.
+
 The `diagram` subcommand
 generates a graph of APIs in [DOT format][dot]
 that can be rendered by [GraphViz][graphviz] into a diagram.

README.md

@@ -105,6 +105,8 @@ extension SwiftDoc {
                         try $0.value.write(to: url, format: format)
                     }
                 }
+            } catch {
+                logger.error("\(error)")
             }
         }
     }

Sources/swift-doc/Subcommands/Generate.swift

@@ -86,7 +86,7 @@ struct Relationships: Component {
         do {
             svg = try HypertextLiteral.HTML(String(data: graph.render(using: algorithm, to: .svg), encoding: .utf8) ?? "")
         } catch {
-            print(error)
+            logger.error("\(error)")
         }
 
         return #"""

Sources/swift-doc/Supporting Types/Components/Relationships.swift

@@ -32,7 +32,7 @@ struct HomePage: Page {
                 globalTypealiasNames.insert(`typealias`.name)
             case let `operator` as Operator:
                 operatorNames.insert(`operator`.name)
-            case let function as Function where !function.isOperator:
+            case let function as Function where function.isOperator:
                 operatorNames.insert(function.name)
             case let function as Function:
                 globalFunctionNames.insert(function.name)

Sources/swift-doc/Supporting Types/Pages/HomePage.swift

@@ -30,7 +30,7 @@ struct SidebarPage: Page {
                 globalTypealiasNames.insert(`typealias`.name)
             case let `operator` as Operator:
                 operatorNames.insert(`operator`.name)
-            case let function as Function where !function.isOperator:
+            case let function as Function where function.isOperator:
                 operatorNames.insert(function.name)
             case let function as Function:
                 globalFunctionNames.insert(function.name)

Sources/swift-doc/Supporting Types/Pages/SidebarPage.swift

@@ -1,5 +1,17 @@
 import ArgumentParser
 import Foundation
+import Logging
+import LoggingGitHubActions
+
+LoggingSystem.bootstrap { label in
+    if ProcessInfo.processInfo.environment["GITHUB_ACTIONS"] == "true" {
+        return GitHubActionsLogHandler.standardOutput(label: label)
+    } else {
+        return StreamLogHandler.standardOutput(label: label)
+    }
+}
+
+let logger = Logger(label: "org.swiftdoc.swift-doc")
 
 let fileManager = FileManager.default
 let fileAttributes: [FileAttributeKey : Any] = [.posixPermissions: 0o744]
@@ -10,8 +22,7 @@ var standardError = FileHandle.standardError
 struct SwiftDoc: ParsableCommand {
     static var configuration = CommandConfiguration(
         abstract: "A utility for generating documentation for Swift code.",
-        subcommands: [Generate.self, Coverage.self, Diagram.self],
-        defaultSubcommand: Generate.self
+        subcommands: [Generate.self, Coverage.self, Diagram.self]
     )
 }