Add docs and release publishing workflows

.github/workflows/publish-docs.yaml

@@ -0,0 +1,79 @@
+name: Publish Docs
+
+on:
+  push:
+    branches: [ main ]
+
+permissions:
+  contents: write
+
+concurrency:
+  group: publish-docs-${{github.ref_name}}
+  cancel-in-progress: false
+
+jobs:
+
+  build:
+
+    runs-on: macos-12
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Select Xcode
+      run: sudo xcode-select -s /Applications/Xcode_14.1.app/Contents/Developer
+
+    - run: |
+        mkdir -p docs
+        mkdir -p allsgs
+        mkdir -p sgs
+
+    - name: Build Symbol Graph
+      run: |
+        swift build -Xswiftc -emit-symbol-graph -Xswiftc -emit-symbol-graph-dir -Xswiftc allsgs
+        cp allsgs/Shield*.json sgs
+
+    - name: Build Docs
+      run: >-
+        swift package 
+        --allow-writing-to-directory docs/${{ github.ref_name }}
+        generate-documentation
+        --enable-inherited-docs
+        --additional-symbol-graph-dir sgs
+        --target Shield
+        --output-path docs/${{ github.ref_name }}
+        --transform-for-static-hosting
+        --hosting-base-path Shield/${{ github.ref_name }}
+
+    - name: Archive Docs
+      run: tar -czf docs.tar.gz docs
+
+    - name: Upload Docs Archive
+      uses: actions/upload-artifact@v3
+      with:
+        name: docs-${{ github.ref_name }}
+        path: docs.tar.gz
+
+  deploy:
+
+    runs-on: ubuntu-latest
+    needs: [ build ]
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Download Docs Archive
+      uses: actions/download-artifact@v3
+      with:
+        name: docs-${{ github.ref_name }}
+        path: '.'
+
+    - name: Unarchive Docs
+      run: tar -xvf docs.tar.gz
+
+    - name: Deploy Docs
+      uses: JamesIves/github-pages-deploy-action@v4
+      with:
+        folder: docs
+        clean: false
+

.github/workflows/publish-release.yaml

@@ -0,0 +1,93 @@
+name: Publish Release
+
+on:
+  push:
+    tags: [ "[0-9]+.[0-9]+.[0-9]+**" ]
+
+permissions:
+  contents: write
+
+concurrency:
+  group: publish-release-${{github.ref_name}}
+  cancel-in-progress: false
+
+jobs:
+
+  build:
+
+    runs-on: macos-12
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Select Xcode
+      run: sudo xcode-select -s /Applications/Xcode_14.1.app/Contents/Developer
+
+    - run: |
+        mkdir -p docs
+        mkdir -p allsgs
+        mkdir -p sgs
+
+    - name: Build Symbol Graph
+      run: |
+        swift build -Xswiftc -emit-symbol-graph -Xswiftc -emit-symbol-graph-dir -Xswiftc allsgs
+        cp allsgs/Shield*.json sgs
+
+    - name: Build Docs
+      run: >-
+        swift package 
+        --allow-writing-to-directory docs/${{ github.ref_name }}
+        generate-documentation
+        --enable-inherited-docs
+        --additional-symbol-graph-dir sgs
+        --target Shield
+        --output-path docs/${{ github.ref_name }}
+        --transform-for-static-hosting
+        --hosting-base-path Shield/${{ github.ref_name }}
+
+    - name: Archive Docs
+      run: tar -czf docs.tar.gz docs
+
+    - name: Upload Docs Archive
+      uses: actions/upload-artifact@v3
+      with:
+        name: docs-${{ github.ref_name }}
+        path: docs.tar.gz
+
+  publish:
+
+    runs-on: ubuntu-latest
+    needs: [ build ]
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Download Docs Archive
+      uses: actions/download-artifact@v3
+      with:
+        name: docs-${{ github.ref_name }}
+        path: '.'
+
+    - name: Unarchive Docs
+      run: tar -xvf docs.tar.gz
+
+    - name: Deploy Docs
+      uses: JamesIves/github-pages-deploy-action@v4
+      with:
+        folder: docs
+        clean: false
+
+    - name: Check Version Format in Tag
+      id: version
+      uses: nowsprinting/check-version-format-action@v3
+
+    - name: Create GitHub Release
+      uses: softprops/action-gh-release@v1
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        name: 🚀 v${{ github.ref_name }}
+        tag_name: ${{ github.ref_name }}
+        generate_release_notes: true
+        prerelease: ${{ steps.version.outputs.is_stable != 'true' }}
+        draft: false

Makefile

@@ -15,6 +15,7 @@ install-tools:
 clean:
 	@rm -rf TestResults
 	@rm -rf .derived-data
+	@rm -rf .build
 
 make-test-results-dir:
 	mkdir -p TestResults
@@ -47,3 +48,17 @@ lint: make-test-results-dir
 
 view_lint: lint
 	open TestResults/lint.html
+
+doc-symbol-graphs:
+	rm -rf .build/all-symbol-graphs || 0
+	rm -rf .build/symbol-graphs || 0
+	mkdir -p .build/all-symbol-graphs
+	mkdir -p .build/symbol-graphs
+	swift build -Xswiftc -emit-symbol-graph -Xswiftc -emit-symbol-graph-dir -Xswiftc .build/all-symbol-graphs
+	cp .build/all-symbol-graphs/Shield*.json .build/symbol-graphs
+
+generate-docs: doc-symbol-graphs
+	swift package --allow-writing-to-directory .build/docs generate-documentation --enable-inherited-docs --additional-symbol-graph-dir .build/symbol-graphs --target Shield --output-path .build/docs --transform-for-static-hosting --hosting-base-path Shield
+
+preview-docs: doc-symbol-graphs
+	swift package --disable-sandbox preview-documentation --enable-inherited-docs --additional-symbol-graph-dir .build/symbol-graphs --target Shield

Package.resolved

@@ -46,6 +46,24 @@
           "version": "1.0.4"
         }
       },
+      {
+        "package": "SwiftDocCPlugin",
+        "repositoryURL": "https://github.com/apple/swift-docc-plugin",
+        "state": {
+          "branch": null,
+          "revision": "10bc670db657d11bdd561e07de30a9041311b2b1",
+          "version": "1.1.0"
+        }
+      },
+      {
+        "package": "SymbolKit",
+        "repositoryURL": "https://github.com/apple/swift-docc-symbolkit",
+        "state": {
+          "branch": null,
+          "revision": "b45d1f2ed151d057b54504d653e0da5552844e34",
+          "version": "1.0.0"
+        }
+      },
       {
         "package": "swift-numerics",
         "repositoryURL": "https://github.com/apple/swift-numerics",

Package.swift

@@ -1,4 +1,4 @@
-// swift-tools-version:5.3
+// swift-tools-version:5.4
 
 import PackageDescription
 
@@ -54,3 +54,11 @@ let package = Package(
     ),
   ]
 )
+
+#if swift(>=5.6)
+
+package.dependencies.append(
+  .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.1.0")
+)
+
+#endif