Merge pull request #357 from mattpolzin/add-swift-docc

Add swift docc based documentation to repo via GitHub pages.

.github/workflows/documentation.yml

@@ -3,14 +3,34 @@ name: Documentation
 on:
   push:
     branches:
-      - main
+      - release/4_0
+      # ^ for now, we only want to use the v4.0 release branch.
 
 jobs:
   build:
     runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v3
+
+      - name: Build Docs
+        run: |
+          mkdir -p ./gh-pages
+          swift package --allow-writing-to-directory ./gh-pages/docs \
+            generate-documentation --include-extended-types \
+                                   --disable-indexing \
+                                   --output-path ./gh-pages/docs \
+                                   --transform-for-static-hosting \
+                                   --hosting-base-path OpenAPIKit \
+                                   --target OpenAPIKit
+
+      - name: Deploy to GitHub Pages
+        uses: JamesIves/[email protected]
+        with:
+          folder: gh-pages
+          branch: gh-pages
+
+
         # TODO: replace the documentation generator with something that is still maintained.
 
 #      - name: Generate Documentation

Package.resolved

@@ -1,16 +1,32 @@
 {
-  "object": {
-    "pins": [
-      {
-        "package": "Yams",
-        "repositoryURL": "https://github.com/jpsim/Yams.git",
-        "state": {
-          "branch": null,
-          "revision": "9ff1cc9327586db4e0c8f46f064b6a82ec1566fa",
-          "version": "4.0.6"
-        }
+  "pins" : [
+    {
+      "identity" : "swift-docc-plugin",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-docc-plugin",
+      "state" : {
+        "revision" : "26ac5758409154cc448d7ab82389c520fa8a8247",
+        "version" : "1.3.0"
       }
-    ]
-  },
-  "version": 1
+    },
+    {
+      "identity" : "swift-docc-symbolkit",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-docc-symbolkit",
+      "state" : {
+        "revision" : "b45d1f2ed151d057b54504d653e0da5552844e34",
+        "version" : "1.0.0"
+      }
+    },
+    {
+      "identity" : "yams",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/jpsim/Yams.git",
+      "state" : {
+        "revision" : "9ff1cc9327586db4e0c8f46f064b6a82ec1566fa",
+        "version" : "4.0.6"
+      }
+    }
+  ],
+  "version" : 2
 }

Package.swift

@@ -20,6 +20,7 @@ let package = Package(
             targets: ["OpenAPIKitCompat"]),
     ],
     dependencies: [
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
         .package(url: "https://github.com/jpsim/Yams.git", "4.0.0"..<"6.0.0") // just for tests
     ],
     targets: [

README.md

@@ -424,4 +424,4 @@ Please see [Security](./SECURITY.md) for information on how to report vulnerabil
 **Please do not report security vulnerabilities via GitHub issues.**
 
 ## Specification Coverage & Type Reference
-For a full list of OpenAPI Specification types annotated with whether OpenAPIKit supports them and relevant translations to OpenAPIKit types, see the [Specification Coverage](./documentation/specification_coverage.md) documentation. For detailed information on the OpenAPIKit types, see the [full type documentation](https://github.com/mattpolzin/OpenAPIKit/wiki).
+For a full list of OpenAPI Specification types annotated with whether OpenAPIKit supports them and relevant translations to OpenAPIKit types, see the [Specification Coverage](./documentation/specification_coverage.md) documentation. For detailed information on the OpenAPIKit types, see the [full type documentation](https://mattpolzin.github.io/OpenAPIKit/documentation/openapikit).