docs: generate api docs (#1)

Adds DocC generated API docs as a CI job on main, published
[here](https://square.github.io/swift-modals/documentation/).

This job uses a [new feature of
DocC](https://forums.swift.org/t/a-preview-of-doccs-support-for-combined-documentation/74373)
to merge modules with a landing page. The inter-module symbol links
don't work yet; I think maybe there's just no way to enable that in
`xcodebuild docbuild`. But the joined navigation and landing page are a
huge improvement.

Author: watt

Diff for: .github/workflows/docs.yaml

@@ -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 }}

Diff for: Samples/Workspace.swift

@@ -8,6 +8,15 @@ let workspace = Workspace(
         // Generate a scheme for each target in Package.swift for convenience
         .modals("Modals"),
         .modals("WorkflowModals"),
+        .scheme(
+            name: "Documentation",
+            buildAction: .buildAction(
+                targets: [
+                    .project(path: "..", target: "Modals"),
+                    .project(path: "..", target: "WorkflowModals"),
+                ]
+            )
+        ),
     ]
 )
 

Diff for: Scripts/generate_docs.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+
+BUILD_PATH=docs_build
+MERGED_PATH=generated_docs
+
+xcodebuild docbuild \
+    -scheme Documentation \
+    -derivedDataPath "$BUILD_PATH" \
+    -workspace Samples/ModalsDevelopment.xcworkspace \
+    -destination generic/platform=iOS \
+    DOCC_HOSTING_BASE_PATH='swift-modals' \
+    | xcpretty
+
+find_archive() {
+    find "$BUILD_PATH" -type d -name "$1.doccarchive" -print -quit
+}
+
+xcrun docc merge \
+    $(find_archive Modals) \
+    $(find_archive WorkflowModals) \
+    --output-path "$MERGED_PATH" \
+    --synthesized-landing-page-name "swift-modals"