docs: add DocC API documentation (#214)

cbaker6 · web-flow · commit 7cbf97b50cdf · 2022-01-21T12:42:14.000-05:00
* Use DocC for documentation

* Remove jazzy badge, create dir

* remove Gem lock file

* build docs in local directory

* place in documentation folder

* fixed find folder

* Try original docs/api link first

* Update change log

* Added initial tutorial

* fix warning

* fix docs build

* Improve doc logo and fix warnings

* clean up
diff --git a/.codecov.yml b/.codecov.yml
@@ -10,6 +10,6 @@ coverage:
     changes: false
     project:
       default:
-        target: 81
+        target: 84
 comment:
   require_changes: true
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -214,6 +214,8 @@ jobs:
     runs-on: macos-latest
     steps:
       - uses: actions/checkout@v2
+      #- name: Build
+      #  run: set -o pipefail && env NSUnbufferedIO=YES xcodebuild docbuild -scheme ParseSwift\ \(macOS\) -derivedDataPath DerivedData | xcpretty
       - name: Cache Gems
         id: cache-gems
         uses: actions/cache@v2
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -43,6 +43,8 @@ jobs:
           bundle install
       - name: Get release version
         run: echo "TAG=${GITHUB_REF/refs\/tags\//}" >> $GITHUB_ENV
+      #- name: Build
+      #  run: set -o pipefail && env NSUnbufferedIO=YES xcodebuild docbuild -scheme ParseSwift\ \(macOS\) -derivedDataPath DerivedData | xcpretty
  #     - name: Use multiple cores
  #       run: defaults write com.apple.dt.XCBuild EnableSwiftBuildSystemIntegration 1
       - name: Create Jazzy Docs
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -21,6 +21,7 @@ __New features__
 __Improvements__
 - (Breaking Change) Change the following method parameter names: isUsingMongoDB -> usingMongoDB, isIgnoreCustomObjectIdConfig -> ignoringCustomObjectIdConfig, isUsingEQ -> usingEqComparator ([#321](https://github.com/parse-community/Parse-Swift/pull/321)), thanks to [Corey Baker](https://github.com/cbaker6).
 - (Breaking Change) Change the following method parameter names: isUsingTransactions -> usingTransactions, isAllowingCustomObjectIds -> allowingCustomObjectIds, isUsingEqualQueryConstraint -> usingEqualQueryConstraint, isMigratingFromObjcSDK -> migratingFromObjcSDK, isDeletingKeychainIfNeeded -> deletingKeychainIfNeeded ([#323](https://github.com/parse-community/Parse-Swift/pull/323)), thanks to [Corey Baker](https://github.com/cbaker6).
+- Add DocC for SDK documentation ([#209](https://github.com/parse-community/Parse-Swift/pull/214)), thanks to [Corey Baker](https://github.com/cbaker6).
 
 ### 3.1.2
 [Full Changelog](https://github.com/parse-community/Parse-Swift/compare/3.1.1...3.1.2)
diff --git a/Package.swift b/Package.swift
@@ -16,6 +16,7 @@ let package = Package(
             dependencies: []),
         .testTarget(
             name: "ParseSwiftTests",
-            dependencies: ["ParseSwift"])
+            dependencies: ["ParseSwift"],
+            exclude: ["Info.plist"])
     ]
 )
diff --git a/ParseSwift.xcodeproj/project.pbxproj b/ParseSwift.xcodeproj/project.pbxproj
@@ -334,6 +334,10 @@
 		7085DDB326D1EC7F0033B977 /* ParseAuthenticationCombineTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 7085DDB226D1EC7F0033B977 /* ParseAuthenticationCombineTests.swift */; };
 		7085DDB426D1EC7F0033B977 /* ParseAuthenticationCombineTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 7085DDB226D1EC7F0033B977 /* ParseAuthenticationCombineTests.swift */; };
 		7085DDB526D1EC7F0033B977 /* ParseAuthenticationCombineTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 7085DDB226D1EC7F0033B977 /* ParseAuthenticationCombineTests.swift */; };
+		7085DD9426CBF3A70033B977 /* Documentation.docc in Sources */ = {isa = PBXBuildFile; fileRef = 7085DD9326CBF3A70033B977 /* Documentation.docc */; };
+		7085DD9526CBF3A70033B977 /* Documentation.docc in Sources */ = {isa = PBXBuildFile; fileRef = 7085DD9326CBF3A70033B977 /* Documentation.docc */; };
+		7085DD9626CBF3A70033B977 /* Documentation.docc in Sources */ = {isa = PBXBuildFile; fileRef = 7085DD9326CBF3A70033B977 /* Documentation.docc */; };
+		7085DD9726CBF3A70033B977 /* Documentation.docc in Sources */ = {isa = PBXBuildFile; fileRef = 7085DD9326CBF3A70033B977 /* Documentation.docc */; };
 		708D035225215F9B00646C70 /* Deletable.swift in Sources */ = {isa = PBXBuildFile; fileRef = 708D035125215F9B00646C70 /* Deletable.swift */; };
 		708D035325215F9B00646C70 /* Deletable.swift in Sources */ = {isa = PBXBuildFile; fileRef = 708D035125215F9B00646C70 /* Deletable.swift */; };
 		708D035425215F9B00646C70 /* Deletable.swift in Sources */ = {isa = PBXBuildFile; fileRef = 708D035125215F9B00646C70 /* Deletable.swift */; };
@@ -962,6 +966,7 @@
 		707A3C1F25B14BCF000D215C /* ParseApple.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ParseApple.swift; sourceTree = "<group>"; };
 		7085DDA226CC8A470033B977 /* ParseHealth+combine.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = "ParseHealth+combine.swift"; sourceTree = "<group>"; };
 		7085DDB226D1EC7F0033B977 /* ParseAuthenticationCombineTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ParseAuthenticationCombineTests.swift; sourceTree = "<group>"; };
+		7085DD9326CBF3A70033B977 /* Documentation.docc */ = {isa = PBXFileReference; lastKnownFileType = folder.documentationcatalog; path = Documentation.docc; sourceTree = "<group>"; };
 		708D035125215F9B00646C70 /* Deletable.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Deletable.swift; sourceTree = "<group>"; };
 		709B40C0268F999000ED2EAC /* IOS13Tests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = IOS13Tests.swift; sourceTree = "<group>"; };
 		709B98302556EC7400507778 /* ParseSwiftTeststvOS.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = ParseSwiftTeststvOS.xctest; sourceTree = BUILT_PRODUCTS_DIR; };
@@ -1349,6 +1354,7 @@
 		4AB8B4F61F254AE10070F682 /* ParseSwift */ = {
 			isa = PBXGroup;
 			children = (
+				7085DD9326CBF3A70033B977 /* Documentation.docc */,
 				4AB8B4F71F254AE10070F682 /* Parse.h */,
 				4A82B7EE1F254B820063D731 /* Parse.swift */,
 				70110D51250680140091CC1D /* ParseConstants.swift */,
@@ -2212,6 +2218,7 @@
 				91679D64268E596300F71809 /* ParseVersion.swift in Sources */,
 				91285B1C26990D7F0051B544 /* ParsePolygon.swift in Sources */,
 				91BB8FCA2690AC99005A6BA5 /* QueryViewModel.swift in Sources */,
+				7085DD9426CBF3A70033B977 /* Documentation.docc in Sources */,
 				F97B45D624D9C6F200F4A88B /* ParseEncoder.swift in Sources */,
 				700395A325A119430052CB31 /* Operations.swift in Sources */,
 				91BB8FCF2690BA70005A6BA5 /* QueryObservable.swift in Sources */,
@@ -2445,6 +2452,7 @@
 				91679D65268E596300F71809 /* ParseVersion.swift in Sources */,
 				91285B1D26990D7F0051B544 /* ParsePolygon.swift in Sources */,
 				91BB8FCB2690AC99005A6BA5 /* QueryViewModel.swift in Sources */,
+				7085DD9526CBF3A70033B977 /* Documentation.docc in Sources */,
 				F97B45D724D9C6F200F4A88B /* ParseEncoder.swift in Sources */,
 				700395A425A119430052CB31 /* Operations.swift in Sources */,
 				91BB8FD02690BA70005A6BA5 /* QueryObservable.swift in Sources */,
@@ -2782,6 +2790,7 @@
 				91679D67268E596300F71809 /* ParseVersion.swift in Sources */,
 				91285B1F26990D7F0051B544 /* ParsePolygon.swift in Sources */,
 				91BB8FCD2690AC99005A6BA5 /* QueryViewModel.swift in Sources */,
+				7085DD9726CBF3A70033B977 /* Documentation.docc in Sources */,
 				F97B465D24D9C78C00F4A88B /* Increment.swift in Sources */,
 				700395A625A119430052CB31 /* Operations.swift in Sources */,
 				91BB8FD22690BA70005A6BA5 /* QueryObservable.swift in Sources */,
@@ -2921,6 +2930,7 @@
 				91679D66268E596300F71809 /* ParseVersion.swift in Sources */,
 				91285B1E26990D7F0051B544 /* ParsePolygon.swift in Sources */,
 				91BB8FCC2690AC99005A6BA5 /* QueryViewModel.swift in Sources */,
+				7085DD9626CBF3A70033B977 /* Documentation.docc in Sources */,
 				F97B465C24D9C78C00F4A88B /* Increment.swift in Sources */,
 				700395A525A119430052CB31 /* Operations.swift in Sources */,
 				91BB8FD12690BA70005A6BA5 /* QueryObservable.swift in Sources */,
diff --git a/Sources/ParseSwift/Documentation.docc/ParseSwift.md b/Sources/ParseSwift/Documentation.docc/ParseSwift.md
@@ -0,0 +1,16 @@
+# ``ParseSwift``
+A pure Swift library that gives you access to the powerful Parse Server backend from your Swift applications.
+
+## Overview
+![Parse logo](parse-swift.png)
+For more information about the Parse Platform and its features, see the public [documentation](https://docs.parseplatform.org). The ParseSwift SDK is not a port of the [Parse-SDK-iOS-OSX SDK](https://github.com/parse-community/Parse-SDK-iOS-OSX) and though some of it may feel familiar, it is not backwards compatible and is designed using [protocol oriented programming (POP) and value types](https://www.pluralsight.com/guides/protocol-oriented-programming-in-swift) instead of OOP and reference types. You can learn more about POP by watching [Protocol-Oriented Programming in Swift](https://developer.apple.com/videos/play/wwdc2015/408/) or [Protocol and Value Oriented Programming in UIKit Apps](https://developer.apple.com/videos/play/wwdc2016/419/) videos from previous WWDC's. For more details about ParseSwift, visit the [api documentation](http://parseplatform.org/Parse-Swift/api/).
+
+To learn how to use or experiment with ParseSwift, you can run and edit the [ParseSwift.playground](https://github.com/parse-community/Parse-Swift/tree/main/ParseSwift.playground/Pages). You can use the parse-server in [this repo](https://github.com/netreconlab/parse-hipaa/tree/parse-swift) which has docker compose files (`docker-compose up` gives you a working server) configured to connect with the playground files, has [Parse Dashboard](https://github.com/parse-community/parse-dashboard), and can be used with MongoDB or PostgreSQL. You can also configure the Swift Playgrounds to work with your own Parse Server by editing the configuation in [Common.swift](https://github.com/parse-community/Parse-Swift/blob/e9ba846c399257100b285d25d2bd055628b13b4b/ParseSwift.playground/Sources/Common.swift#L4-L19). To learn more, check out [CONTRIBUTING.md](https://github.com/parse-community/Parse-Swift/blob/main/CONTRIBUTING.md#swift-playgrounds).
+
+## Topics
+
+### Initialize the SDK
+
+- ``ParseSwift/ParseSwift/initialize(configuration:)``
+- ``ParseSwift/ParseSwift/initialize(applicationId:clientKey:masterKey:serverURL:liveQueryServerURL:allowingCustomObjectIds:usingTransactions:usingEqualQueryConstraint:keyValueStore:requestCachePolicy:cacheMemoryCapacity:cacheDiskCapacity:migratingFromObjcSDK:deletingKeychainIfNeeded:httpAdditionalHeaders:maxConnectionAttempts:authentication:)``
+
diff --git a/Sources/ParseSwift/Documentation.docc/ParseSwift.tutorial b/Sources/ParseSwift/Documentation.docc/ParseSwift.tutorial
@@ -0,0 +1,12 @@
+@Tutorials(name: "ParseSwift") {
+    @Intro(title: "Welcome to ParseSwift") {
+        
+    }
+    
+    @Chapter(name: "Your first Object") {
+        
+        @Image(source: parse.png, alt: "Parse image")
+        
+        @TutorialReference(tutorial: "doc:Your-First-Object")
+    }
+}
diff --git a/Sources/ParseSwift/Documentation.docc/Resources/parse-swift.png b/Sources/ParseSwift/Documentation.docc/Resources/parse-swift.png
diff --git a/Sources/ParseSwift/Documentation.docc/Your First Object.tutorial b/Sources/ParseSwift/Documentation.docc/Your First Object.tutorial
@@ -0,0 +1,14 @@
+@Tutorial(time: 15) {
+    @Intro(title: "Your First Object") {
+        
+    }
+    
+    @Section(title: "Check server health") {
+        @Steps {
+            
+            @Step {
+                Check your server health.
+            }
+        }
+    }
+}
diff --git a/Sources/ParseSwift/LiveQuery/ParseLiveQuery.swift b/Sources/ParseSwift/LiveQuery/ParseLiveQuery.swift
@@ -17,23 +17,23 @@ import FoundationNetworking
  
  In most cases, you should not call this class directly as a LiveQuery can be indirectly
  created from `Query` using:
-    
-     // If "Message" is a "ParseObject"
-     let myQuery = Message.query("from" == "parse")
-     guard let subscription = myQuery.subscribe else {
-         "Error subscribing..."
-         return
+ ```swift
+ // If "Message" is a "ParseObject"
+ let myQuery = Message.query("from" == "parse")
+ guard let subscription = myQuery.subscribe else {
+     "Error subscribing..."
+     return
+ }
+ subscription.handleSubscribe { subscribedQuery, isNew in
+
+     //Handle the subscription however you like.
+     if isNew {
+         print("Successfully subscribed to new query \(subscribedQuery)")
+     } else {
+         print("Successfully updated subscription to new query \(subscribedQuery)")
      }
-     subscription.handleSubscribe { subscribedQuery, isNew in
-
-         //Handle the subscription however you like.
-         if isNew {
-             print("Successfully subscribed to new query \(subscribedQuery)")
-         } else {
-             print("Successfully updated subscription to new query \(subscribedQuery)")
-         }
-     }
- 
+ }
+ ```
  The above creates a `ParseLiveQuery` using either the `liveQueryServerURL` (if it has been set)
  or `serverURL` when using `ParseSwift.initialize`. All additional queries will be
  created in the same way. The times you will want to initialize a new `ParseLiveQuery` instance

Original file line number	Diff line number	Diff line change
`@@ -16,6 +16,7 @@ let package = Package(`
`16`	`16`	`dependencies: []),`
`17`	`17`	`.testTarget(`
`18`	`18`	`name: "ParseSwiftTests",`
`19`		`- dependencies: ["ParseSwift"])`
	`19`	`+ dependencies: ["ParseSwift"],`
	`20`	`+ exclude: ["Info.plist"])`
`20`	`21`	`]`
`21`	`22`	`)`