docs: DocC API docs (#338)

Adds DocC generated API docs, published
[here](https://square.github.io/workflow-swift/documentation/), and
removes the old doc generation pipeline.

Author: watt

.buildscript/build_swift_docs.sh

@@ -0,0 +1,40 @@
+name: Generate and publish docs
+
+on:
+  push:
+    branches: [ main ]
+
+env:
+  # Xcode 16.3 gets us Swift 6.1, required for docc merge
+  XCODE_VERSION: 16.3
+
+jobs:
+  build:
+    name: Generate API docs and publish to GitHub pages
+    # macos-15 is required for Xcode 16.3
+    runs-on: macos-15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - uses: jdx/mise-action@5083fe46898c414b2475087cc79da59e7da859e8
+      - uses: maxim-lobanov/setup-xcode@60606e260d2fc5762a71e64e74b2174e8ea3c8bd
+        with:
+          xcode-version: ${{ env.XCODE_VERSION }}
+
+      - name: Install dependencies
+        run: tuist install --path Samples
+
+      - name: Generate project
+        run: tuist generate --path Samples --no-open
+
+      - name: Generate Docs
+        run: Scripts/generate_docs.sh
+
+      - name: Deploy to GitHub Pages
+        uses: crazy-max/ghaction-github-pages@df5cc2bfa78282ded844b354faee141f06b41865
+        with:
+          target_branch: gh-pages
+          build_dir: generated_docs
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.buildscript/update_changelog.swift

@@ -66,23 +66,6 @@ jobs:
     - name: Tutorial App
       run: tuist test --path Samples/Tutorial TutorialTests
 
-  documentation-lint:
-    runs-on: macos-latest
-
-    steps:
-    - uses: actions/checkout@v4
-    - uses: jdx/mise-action@v2
-
-    - name: Switch Xcode
-      run: sudo xcode-select -s /Applications/Xcode_${XCODE_VERSION}.app
-
-    - name: Install sourcedocs
-      run: brew install sourcedocs
-
-    - name: Swiftdocs
-      run: |
-        .buildscript/build_swift_docs.sh ${{ runner.temp }}/swiftdocs
-
   swiftformat:
     runs-on: macos-latest
 

.github/workflows/docs.yaml

@@ -60,7 +60,7 @@ let package = Package(
         .package(url: "https://github.com/ReactiveCocoa/ReactiveSwift.git", from: "7.1.1"),
         .package(url: "https://github.com/ReactiveX/RxSwift.git", from: "6.6.0"),
         .package(url: "https://github.com/swiftlang/swift-syntax", "509.0.0" ..< "601.0.0-prerelease"),
-        .package(url: "https://github.com/pointfreeco/swift-case-paths", from: "1.1.0"),
+        .package(url: "https://github.com/pointfreeco/swift-case-paths", from: "1.5.5"),
         .package(url: "https://github.com/pointfreeco/swift-identified-collections", from: "1.0.0"),
         .package(url: "https://github.com/pointfreeco/swift-macro-testing", from: "0.4.0"),
         .package(url: "https://github.com/pointfreeco/swift-perception", from: "1.5.0"),

.github/workflows/swift.yaml

@@ -22,6 +22,19 @@ let workspace = Workspace(
         .workflow("ViewEnvironment"),
         .workflow("ViewEnvironmentUI"),
         .workflow("WorkflowSwiftUIExperimental"),
+        .scheme(
+            name: "Documentation",
+            buildAction: .buildAction(
+                targets: [
+                    .project(path: "..", target: "ViewEnvironment"),
+                    .project(path: "..", target: "ViewEnvironmentUI"),
+                    .project(path: "..", target: "Workflow"),
+                    .project(path: "..", target: "WorkflowSwiftUI"),
+                    .project(path: "..", target: "WorkflowTesting"),
+                    .project(path: "..", target: "WorkflowUI"),
+                ]
+            )
+        ),
     ]
 )
 

.markdownlint.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+BUILD_PATH=docs_build
+MERGED_PATH=generated_docs
+REPO_NAME=workflow-swift
+
+xcodebuild docbuild \
+    -scheme Documentation \
+    -derivedDataPath "$BUILD_PATH" \
+    -workspace Samples/WorkflowDevelopment.xcworkspace \
+    -destination generic/platform=iOS \
+    DOCC_HOSTING_BASE_PATH="$REPO_NAME" \
+    | xcpretty
+
+find_archive() {
+    find "$BUILD_PATH" -type d -name "$1.doccarchive" -print -quit
+}
+
+xcrun docc merge \
+    $(find_archive ViewEnvironment) \
+    $(find_archive ViewEnvironmentUI) \
+    $(find_archive Workflow) \
+    $(find_archive WorkflowSwiftUI) \
+    $(find_archive WorkflowTesting) \
+    $(find_archive WorkflowUI) \
+    --output-path "$MERGED_PATH" \
+    --synthesized-landing-page-name "$REPO_NAME"