Some more improvements (#28)

gwynne · web-flow · commit 6c0c3663466d · 2023-08-07T06:11:27.000-05:00
* Add some icons * Pretty up generate-package-api-docs.swift a bit * Work around swiftlang/swift-corelibs-foundation#4808
diff --git a/.github/workflows/deploy-api-docs.yml b/.github/workflows/deploy-api-docs.yml
@@ -8,50 +8,43 @@ jobs:
   deploy:
     name: Build and deploy
     runs-on: ubuntu-latest
-    container:
-      image: swift:5.7
+    container: swiftlang/swift:nightly-5.9-jammy@sha256:a3c3ec5e4436c14e44759e38416bb0d46813dc6dd050e787ef3a80b2c3051a36
     steps:
-    - name: Checkout
-      uses: actions/checkout@v3
-    - name: Build site
-      run: swift generate-api-docs.swift
-    - name: Configure AWS Credentials
-      id: cred
-      uses: aws-actions/configure-aws-credentials@v1
-      with:
-        aws-access-key-id: ${{ secrets.API_DOCS_DEPLOYER_AWS_ACCESS_KEY_ID }}
-        aws-secret-access-key: ${{ secrets.API_DOCS_DEPLOYER_AWS_SECRET_ACCESS_KEY }}
-        aws-region: 'eu-west-2'
-    - name: Deploy to AWS CloudFormation
-      id: clouddeploy
-      uses: aws-actions/aws-cloudformation-github-deploy@v1.0.3
-      with:
-        name: vapor-api-docs
-        template: stack.yaml
-        no-fail-on-empty-changeset: '1'
-        parameter-overrides: >-
-          BucketName=vapor-api-docs-site,
-          SubDomainName=api,
-          HostedZoneName=vapor.codes,
-          AcmCertificateArn=${{ secrets.API_DOCS_CERTIFICATE_ARN }}
-      if: steps.cred.outcome == 'success'
-    - name: Deploy to S3
-      id: s3deploy
-      uses: jakejarvis/s3-sync-action@master
-      with:
-        args: --acl public-read --follow-symlinks
-      env:
-        AWS_S3_BUCKET: 'vapor-api-docs-site'
-        AWS_ACCESS_KEY_ID: ${{ secrets.API_DOCS_DEPLOYER_AWS_ACCESS_KEY_ID }}
-        AWS_SECRET_ACCESS_KEY: ${{ secrets.API_DOCS_DEPLOYER_AWS_SECRET_ACCESS_KEY }}
-        AWS_REGION: 'eu-west-2'
-        SOURCE_DIR: 'public'
-      if: steps.clouddeploy.outcome == 'success'
-    - name: Invalidate CloudFront
-      uses: awact/cloudfront-action@master
-      env:
-        SOURCE_PATH: '/*'
-        AWS_ACCESS_KEY_ID: ${{ secrets.API_DOCS_DEPLOYER_AWS_ACCESS_KEY_ID }}
-        AWS_SECRET_ACCESS_KEY: ${{ secrets.API_DOCS_DEPLOYER_AWS_SECRET_ACCESS_KEY }}
-        AWS_REGION: 'eu-west-2'
-        DISTRIBUTION_ID: ${{ secrets.VAPOR_API_DOCS_DISTRIBUTION_ID }}
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Build site
+        run: swift generate-api-docs.swift
+      - name: Install curl and awscliv2
+        run: | 
+          apt-get update && apt-get upgrade -y && apt-get install -y curl
+          curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
+          unzip awscliv2.zip
+          ./aws/install
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@v2
+        with:
+          aws-access-key-id: ${{ secrets.API_DOCS_DEPLOYER_AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.API_DOCS_DEPLOYER_AWS_SECRET_ACCESS_KEY }}
+          aws-region: 'eu-west-2'
+      - name: Deploy to AWS CloudFormation
+        uses: aws-actions/aws-cloudformation-github-deploy@v1
+        with:
+          name: vapor-api-docs
+          template: stack.yaml
+          no-fail-on-empty-changeset: '1'
+          parameter-overrides: >-
+            BucketName=vapor-api-docs-site,
+            SubDomainName=api,
+            HostedZoneName=vapor.codes,
+            AcmCertificateArn=${{ secrets.API_DOCS_CERTIFICATE_ARN }}
+      - name: Deploy to S3 and invalidate CloudFront
+        env:
+          DISTRIBUTION_ID: ${{ secrets.VAPOR_API_DOCS_DISTRIBUTION_ID }}
+        run: |
+          aws --no-cli-pager s3 sync \
+            ./public s3://vapor-api-docs-site \
+            --no-progress \
+            --acl public-read
+          aws --no-cli-pager cloudfront create-invalidation \
+            --distribution-id ${DISTRIBUTION_ID} \
+            --paths '/*'
diff --git a/generate-api-docs.swift b/generate-api-docs.swift
@@ -39,84 +39,27 @@ let packages: [String: [String]] = [
     "apns": ["VaporAPNS"],
 ]
 
-try shell("rm", "-rf", "public/")
-let url = URL(fileURLWithPath: "index.html")
-var htmlString = try String(contentsOf: url)
-var optionsString = ""
-var allModules: [(package: String, module: String)] = []
+let htmlMenu = packages.values.flatMap { $0 }
+    .sorted()
+    .map { "<option value=\"\($0.lowercased())/documentation/\($0.lowercased())\">\($0)</option>" }
+    .joined(separator: "\n")
 
-for (package, modules) in packages {
-    for module in modules {
-        allModules.append((package: package, module: module))
-    }
-}
-
-let sortedModules = allModules.sorted { $0.module < $1.module }
-for object in sortedModules {
-    let module = object.module
-    optionsString += "<option value=\"/\(module.lowercased())/documentation/\(module.lowercased())\">\(module)</option>\n"
-}
-
-htmlString = htmlString.replacingOccurrences(of: "{{Options}}", with: optionsString)
-
-try shell("mkdir", "public")
-try htmlString.write(toFile: "public/index.html", atomically: true, encoding: .utf8)
-try shell("cp", "api-docs.png", "public/api-docs.png")
-try shell("cp", "error.html", "public/error.html")
-
-// MARK: Functions
-@discardableResult
-func shell(_ args: String..., returnStdOut: Bool = false, stdIn: Pipe? = nil) throws -> Pipe {
-    let task = Process()
-    task.launchPath = "/usr/bin/env"
-    task.arguments = args
-    let pipe = Pipe()
-    if returnStdOut {
-        task.standardOutput = pipe
-    }
-    if let stdIn = stdIn {
-        task.standardInput = stdIn
-    }
-    try task.run()
-    task.waitUntilExit()
-    guard task.terminationStatus == 0 else {
-        throw ShellError(terminationStatus: task.terminationStatus)
-    }
-    return pipe
-}
+let publicDirUrl = URL(fileURLWithPath: "./public", isDirectory: true)
+try FileManager.default.removeItem(at: publicDirUrl)
+try FileManager.default.createDirectory(at: publicDirUrl, withIntermediateDirectories: true)
 
-struct ShellError: Error {
-    var terminationStatus: Int32
-}
+var htmlIndex = try String(contentsOf: URL(fileURLWithPath: "./index.html", isDirectory: false), encoding: .utf8)
+htmlIndex.replace("{{Options}}", with: "\(htmlMenu)\n", maxReplacements: 1)
 
-extension Pipe {
-    func string() throws -> String? {
-        let data = try self.fileHandleForReading.readToEnd()!
-        let result: String?
-        if let string = String(
-            data: data, 
-            encoding: String.Encoding.utf8
-        ) {
-            result = string
-        } else {
-            result = nil
-        }
-        return result
-    }
-} 
+try htmlIndex.write(to: publicDirUrl.appendingPathComponent("index.html", isDirectory: false), atomically: true, encoding: .utf8)
+try FileManager.copyItem(at: URL(fileURLWithPath: "./api-docs.png", isDirectory: false), into: publicDirUrl)
+try FileManager.copyItem(at: URL(fileURLWithPath: "./error.html", isDirectory: false), into: publicDirUrl)
 
 extension FileManager {
-    func copyItemIfPossible(atPath: String, toPath: String) throws {
-        var isDirectory: ObjCBool = false
-        guard self.fileExists(
-                atPath: toPath,
-                isDirectory: &isDirectory
-            ) == false else {
-                return
-            }
-        return try self.copyItem(
-            atPath: atPath,
-            toPath: toPath
-        )
+    func copyItem(at src: URL, into dst: URL) throws {
+        assert(dst.hasDirectoryPath)
+
+        let dstItem = dst.appendingPathComponent(src.lastPathComponent, isDirectory: src.hasDirectoryPath)
+        try self.copyItem(at: src, to: dstItem)
     }
 }
diff --git a/generate-package-api-docs.swift b/generate-package-api-docs.swift
@@ -10,8 +10,7 @@ let moduleList = CommandLine.arguments[2]
 
 let modules = moduleList.components(separatedBy: ",")
 
-let currentDirectoryUrl = URL(fileURLWithPath: FileManager.default.currentDirectoryPath, isDirectory: true)
-let publicDirectoryUrl = currentDirectoryUrl.appendingPathComponent("public", isDirectory: true)
+let publicDirectoryUrl = URL.currentDirectory().appending(component: "public/")
 
 try run()
 
@@ -34,7 +33,7 @@ func run() throws {
 }
 
 func ensurePluginAvailable() throws {
-    let manifestUrl = currentDirectoryUrl.appendingPathComponent("Package.swift", isDirectory: false)
+    let manifestUrl = URL.currentDirectory().appending(component: "Package.swift")
     var manifestContents = try String(contentsOf: manifestUrl, encoding: .utf8)
     if !manifestContents.contains(".package(url: \"https://github.com/apple/swift-docc-plugin") {
         // This is freely admitted to be quick and dirty. When SE-0301 gets into a release, we can use that.
@@ -54,7 +53,7 @@ func ensurePluginAvailable() throws {
 func generateDocs(module: String) throws {
     print("🔎  Finding DocC catalog")
     let doccCatalogs = try FileManager.default.contentsOfDirectory(
-        at: currentDirectoryUrl.appendingPathComponent("Sources", isDirectory: true).appendingPathComponent(module, isDirectory: true),
+        at: URL.currentDirectory().appending(components: "Sources", "\(module)/"),
         includingPropertiesForKeys: nil,
         options: [.skipsSubdirectoryDescendants]
     ).filter { $0.hasDirectoryPath && $0.pathExtension == "docc" }
@@ -70,14 +69,10 @@ func generateDocs(module: String) throws {
     print("🗂️  Using DocC catalog \(doccCatalogUrl.lastPathComponent)")
 
     print("📐  Copying theme")
-    do {
-        try FileManager.default.copyItemIfExistsWithoutOverwrite(
-            at: currentDirectoryUrl.appendingPathComponent("theme-settings.json", isDirectory: false),
-            to: doccCatalogUrl.appendingPathComponent("theme-settings.json", isDirectory: false)
-        )
-    } catch CocoaError.fileReadNoSuchFile, CocoaError.fileWriteFileExists {
-		// ignore
-    }
+    try FileManager.default.copyItemIfExistsWithoutOverwrite(
+        at: URL.currentDirectory().appending(component: "theme-settings.json"),
+        to: doccCatalogUrl.appending(component: "theme-settings.json")
+    )
     
     print("📝  Generating docs")
     try shell([
@@ -92,7 +87,7 @@ func generateDocs(module: String) throws {
         "--fallback-bundle-version", "1.0.0",
         "--transform-for-static-hosting",
         "--hosting-base-path", "/\(module.lowercased())",
-        "--output-path", publicDirectoryUrl.appendingPathComponent(module.lowercased(), isDirectory: true).path,
+        "--output-path", publicDirectoryUrl.appending(component: "\(module.lowercased())/").path,
     ])
 }
 
@@ -111,7 +106,7 @@ func shell(_ args: [String]) throws {
     }
 
     // Run the command:
-    let task = try Process.run(URL(fileURLWithPath: "/usr/bin/env", isDirectory: false), arguments: args)
+    let task = try Process.run(URL(filePath: "/usr/bin/env"), arguments: args)
     task.waitUntilExit()
     guard task.terminationStatus == 0 else {
         throw ShellError(terminationStatus: task.terminationStatus)
@@ -126,18 +121,51 @@ extension FileManager {
     func removeItemIfExists(at url: URL) throws {
         do {
             try self.removeItem(at: url)
-        } catch let error as NSError where error.domain == CocoaError.errorDomain && error.code == CocoaError.fileNoSuchFile.rawValue {
+        } catch let error as NSError where error.isCocoaError(.fileNoSuchFile) {
             // ignore
         }
     }
     
     func copyItemIfExistsWithoutOverwrite(at src: URL, to dst: URL) throws {
         do {
+            // https://github.com/apple/swift-corelibs-foundation/pull/4808
+            #if !canImport(Darwin)
+            do {
+                _ = try dst.checkResourceIsReachable()
+                throw NSError(domain: CocoaError.errorDomain, code: CocoaError.fileWriteFileExists.rawValue)
+            } catch let error as NSError where error.isCocoaError(.fileReadNoSuchFile) {}
+            #endif
             try self.copyItem(at: src, to: dst)
-        } catch let error as NSError where error.domain == CocoaError.errorDomain && error.code == CocoaError.fileReadNoSuchFile.rawValue {
+        } catch let error as NSError where error.isCocoaError(.fileReadNoSuchFile) {
             // ignore
-        } catch let error as NSError where error.domain == CocoaError.errorDomain && error.code == CocoaError.fileWriteFileExists.rawValue {
+        } catch let error as NSError where error.isCocoaError(.fileWriteFileExists) {
             // ignore
         }
     }
 }
+
+extension NSError {
+    func isCocoaError(_ code: CocoaError.Code) -> Bool {
+        self.domain == CocoaError.errorDomain && self.code == code.rawValue
+    }
+}
+
+#if !canImport(Darwin)
+extension URL {
+    public enum DirectoryHint: Equatable { case isDirectory, notDirectory, inferFromPath }
+    static func isDirFlag(_ path: some StringProtocol, _ hint: DirectoryHint) -> Bool {
+        hint == .inferFromPath ? path.last == "/" : hint == .isDirectory
+    }
+    public init(filePath: String, directoryHint hint: DirectoryHint = .inferFromPath, relativeTo base: URL? = nil) {
+        self = URL(fileURLWithPath: filePath, isDirectory: Self.isDirFlag(path, hint), relativeTo: base)
+    }
+    public func appending(component: some StringProtocol, directoryHint hint: DirectoryHint = .inferFromPath) -> URL {
+        self.appendingPathComponent(component, isDirectory: Self.isDirFlag(component, hint))
+    }
+    public func appending(components: (some StringProtocol)..., directoryHint hint: DirectoryHint = .inferFromPath) -> URL {
+        components.dropLast().reduce(self) { $0.appending(component: $1, directoryHint: .isDirectory) }
+            .appending(component: components.last!, directoryHint: hint)
+    }
+    public static func currentDirectory() -> URL { .init(filePath: FileManager.default.currentDirectoryPath, directoryHint: .isDirectory) }
+}
+#endif
diff --git a/images/article.svg b/images/article.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 14 14" id="article"><g transform="translate(3.616699, 1.608398)"><path d="M0.0136063,12.3984375H6.948308c1.3516788,0,2.0242538-0.6856346,2.0242538-2.0438433V4.4254899c0-0.842351-0.0979481-1.2080226-0.6203365-1.7434704L4.7542777-0.9812267C4.2580094-1.490555,3.8466287-1.6015625,3.1152854-1.6015625H0.0136063c-1.3451493,0-2.0242538,0.6921641-2.0242538,2.0503731v9.9057837C-2.0106475,11.7193327-1.3380729,12.3984375,0.0136063,12.3984375zM0.0593152,11.3471317c-0.6725746,0-1.0186567-0.3591423-1.0186567-1.0121269V0.4684002c0-0.6464552,0.346082-1.0186567,1.0251865-1.0186567h2.9057837v3.7938433c0,0.8227613,0.4113805,1.2276118,1.227612,1.2276118h3.7220149v5.8638062c0,0.6529846-0.3460822,1.0121269-1.0251865,1.0121269H0.0593152zM4.3167777,3.4851911c-0.2611938,0-0.3591416-0.1044776-0.3591416-0.3656716v-3.4673507l3.761194,3.8330224H4.3167777zM5.8839421,6.2734375H0.9277854c-0.2350746,0-0.4113806,0.1763058-0.4113806,0.3983207c0,0.2285452,0.176306,0.404851,0.4113806,0.404851h4.9561567c0.2285447,0,0.3983207-0.1763058,0.3983207-0.404851C6.2822628,6.4497433,6.1124868,6.2734375,5.8839421,6.2734375zM5.8839421,8.5523558H0.9277854c-0.2350746,0-0.4113806,0.1828356-0.4113806,0.4113798c0,0.2220154,0.176306,0.3917913,0.4113806,0.3917913h4.9561567c0.2285447,0,0.3983207-0.169776,0.3983207-0.3917913C6.2822628,8.7351913,6.1124868,8.5523558,5.8839421,8.5523558z"></path></g></svg>
diff --git a/images/collection.svg b/images/collection.svg
@@ -0,0 +1,4 @@
+<svg viewBox="0 0 14 14" xmlns="http://www.w3.org/2000/svg" id="collection">
+ <title>Collection</title>
+ <path transform="translate(2.117 4.456)" d="m-1.241-.7678c.7106.04 1.156-.9012.6762-1.426-.4217-.566-1.429-.32-1.534.38-.123.526.32 1.062.858 1.046zm3.071-.3122h9.49c.8.03.67-1.276-.1-1.119h-9.39c-.738-.01-.743 1.13 0 1.119zm-3.071 4.516c.7132.04 1.155-.908.6762-1.434-.4217-.566-1.429-.32-1.534.381-.122.526.316 1.068.858 1.053zm3.071-.313h9.49c.8.02.67-1.275-.1-1.119h-9.39c-.741-.01-.739 1.125 0 1.119zm-3.071 4.516c.711.037 1.155-.907.6762-1.433-.4217-.566-1.429-.32-1.534.38-.122.525.318 1.067.858 1.053zm3.071-.319h9.49c.8.03.67-1.276-.1-1.119h-9.39c-.738-.01-.743 1.13 0 1.119z"/>
+</svg>
diff --git a/images/curly-brackets.svg b/images/curly-brackets.svg
@@ -0,0 +1,3 @@
+<svg viewBox="0 0 14 14" xmlns="http://www.w3.org/2000/svg" id="curly-brackets">
+ <path d="m.6859 7.011c.01.855 1.123.662 1.557 1.156.404.611.3 1.401.312 2.103-.03 1.05-.119 2.31.684 3.12.589.52 1.449.73 2.213.59.837-.48-.07-1.27-.745-1.06-.769-.21-1.077-1.1-.986-1.82-.036-1.105.171-2.265-.228-3.314-.148-.426-1.245-.634-1.091-.814.849-.17 1.387-1.013 1.324-1.851.057-1.062-.107-2.138.101-3.188.24-.9854 1.597-.576 1.996-1.323-.138-.8405-1.182-.6631-1.773-.4471-.858.2759-1.453 1.115-1.468 2.012-.138 1.188.168 2.43-.233 3.582-.368.66-1.656.316-1.663 1.254zm12.62 0c-.04-.945-1.37-.572-1.67-1.322-.53-1.41.14-2.991-.46-4.393-.39-1.013-1.621-1.399-2.614-1.258-.813.3763-.089 1.325.606 1.06.838.129 1.198 1.063 1.098 1.817-0 1.084-.1 2.191.17 3.252.25.48.8.722 1.3.867-.9.06-1.52.948-1.46 1.809-.1 1.154.17 2.347-.19 3.467-.37.68-1.272.52-1.841.92-.337.94 1.089.92 1.642.65.929-.25 1.539-1.21 1.519-2.15.14-1.17-.21-2.423.3-3.526.42-.552 1.61-.291 1.6-1.193z"/>
+</svg>
diff --git a/theme-settings.json b/theme-settings.json
@@ -21,7 +21,13 @@
                 "dark": "rgb(20, 20, 22)",
                 "light": "rgb(255, 255, 255)"
             },
-            "documentation-intro-fill": "radial-gradient(circle at top, #ccc 15%, #111 100%)"
+            "documentation-intro-fill": "radial-gradient(circle at top, var(--color-documentation-intro-accent) 15%, rgb(17, 17, 17) 100%)",
+            "documentation-intro-accent": "rgb(204, 204, 204)"
+        },
+        "icons": {
+            "article": "/images/article.svg",
+            "collection": "/images/collection.svg",
+            "curly-brackets": "/images/curly-brackets.svg"
         }
     },
     "features": {
