Add more articles (#281)

* Add more Gravatar articles

* Add more GravatarUI articles

* Update the main README to point to the hosted docs

* Apply suggestions from code review

Co-authored-by: etoledom <[email protected]>

* Remove Articles list from Gravatar.md

* Merge items under the list

* Make 'Add Package' bold

* Merge items under the list

---------

Co-authored-by: etoledom <[email protected]>

README.md

@@ -24,6 +24,13 @@ Follow the steps in the [REST API documentation](https://docs.gravatar.com/api/p
 
 For installation instructions and examples, see out [getting started](Sources/Gravatar/Gravatar.docc/GettingStarted.md) guide.
 
+## Documentation
+
+You can find some detailed articles, tutorials and API docs via these links:
+
+- [Gravatar docs](https://automattic.github.io/Gravatar-SDK-iOS/gravatar/documentation/gravatar/)
+- [GravatarUI docs](https://automattic.github.io/Gravatar-SDK-iOS/gravatarui/documentation/gravatarui/)
+
 ## Author
 
 Gravatar

Sources/Gravatar/Gravatar.docc/1. GettingStarted.md

@@ -0,0 +1,57 @@
+# Getting started
+Install and start using Gravatar for iOS
+
+## Installation
+
+### Swift Package Manager
+
+##### Adding Gravatar SDK to an iOS project in Xcode:
+- File > Add Package Dependency
+- Search by https://github.com/Automattic/Gravatar-SDK-iOS.git
+- Click on **Add Package**
+
+For more info, check the [Apple Docs](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app).
+
+##### Adding Gravatar to a SPM project:
+
+1. Add the `Gravatar-SDK-iOS` as a dependency of your project. Recommended to use the [latest tagged version](https://github.com/Automattic/Gravatar-SDK-iOS/tags).
+2. Add the `Gravatar` product as a dependency of your target.
+
+```swift
+let package = Package(
+    name: "Package Name",
+    dependencies: [
+        // 1.
+        .package(url: "https://github.com/Automattic/Gravatar-SDK-iOS.git", from: "x.y.z")
+    ],
+    targets: [
+        .executableTarget(
+            name: "Target Name",
+            dependencies: [
+                // 2.
+                .product(name: "Gravatar", package: "Gravatar")
+            ]
+        )
+    ]
+)
+```
+### CocoaPods
+
+Add `pod 'Gravatar'` to your target in your `PODFILE`. 
+
+```ruby
+source 'https://github.com/CocoaPods/Specs.git'
+use_frameworks!
+
+target 'MyApp' do
+    pod 'Gravatar'
+end
+```
+
+## Articles
+
+@Links(visualStyle: list) {
+    - <doc:2.-DownloadingAvatar>
+    - <doc:3.-UploadingAvatar>
+    - <doc:4.-FetchingProfile>
+}

Sources/Gravatar/Gravatar.docc/2. DownloadingAvatar.md

@@ -0,0 +1,101 @@
+#  Downloading an Avatar
+
+Download an avatar provided by Gravatar.
+
+## Download Avatar via email
+
+Use the ``AvatarService`` to download an avatar image:
+
+```swift
+import Gravatar
+
+// [...]
+
+Task {
+    await fetchAvatar(with: "[email protected]")
+}
+
+func fetchAvatar(with email: String) async {
+    let service = AvatarService()
+
+    do {
+        let result = try await service.fetchImage(with: .email(email))
+        updateAvatar(with: result.image)
+    } catch {
+        print(error)
+    }
+}
+
+@MainActor
+func updateAvatar(with image: UIImage) {
+    avatarImageView.image = image
+}
+```
+
+### Download Options
+
+Check out ``ImageDownloadOptions`` and [the backend documentation](https://docs.gravatar.com/api/avatars/images/). Pass your preferences about the avatar size, rating etc. Even though each option has a default value we highly encourage you to investigate the provided documentation and set your own values because they can have big impact on the result.
+
+```swift
+import Gravatar
+
+let service = AvatarService()
+let options = ImageDownloadOptions(preferredSize: .points(50),
+                                   rating: .general,
+                                   forceRefresh: false,
+                                   defaultAvatarOption: .mysteryPerson)
+let result = try await service.fetch(with: .email("[email protected]"), options: options)
+
+```
+
+#### Providing a custom ImageProcessor
+
+If you want to control the way the downloaded `Data` is converted into a `UIImage` you can implement your own ``ImageProcessor``.
+
+
+```swift
+import Gravatar
+
+struct CustomImageProcessor: ImageProcessor {
+    func process(_ data: Data) -> UIImage? {
+        let result: UIImage?
+        // work on the data
+        // result = ...
+        return result
+    }
+}
+
+let service = AvatarService()
+let options = ImageDownloadOptions(processingMethod: .custom(processor: CustomImageProcessor()))
+let result = try await service.fetch(with: .email("[email protected]"), options: options)
+
+```
+
+## Download Avatar via URL
+
+Sometimes you may need to download the Avatar based on a URL. You may also need to apply different options on the URL.
+
+Use ``AvatarURL`` and ``ImageDownloadService`` to achieve this.
+
+
+```swift
+import Gravatar
+
+// [...]
+
+let options = AvatarQueryOptions(preferredPixelSize: 120,
+                                 rating: .restricted,
+                                 defaultAvatarOption: .mysteryPerson)
+
+// `AvatarURL` takes care of removing the query parameters in the initial URL and reconstructing the URL based on the given options.
+
+guard let url = URL(string: "https://gravatar.com/avatar/b815b4f3f5e4be2256bce9e25eac7714?r=pg&s=150"),
+      let avatarURL = AvatarURL(url: url, options: options)?.url else {
+    // handle the unexpected state
+}
+
+let service = ImageDownloadService()
+let result = try await service.fetchImage(with: avatarURL)
+
+```
+

Sources/Gravatar/Gravatar.docc/3. UploadingAvatar.md

@@ -0,0 +1,25 @@
+#  Uploading an Avatar
+
+Let a user to update their avatar.
+
+You can provide a way to upload a new avatar for your users who have a Gravatar account.
+
+At the moment, Gravatar uses WordPress.com OAuth2 access token. Thus, you need a WordPress.com access token to update a user's avatar. Check out [the documentation](https://developer.wordpress.com/docs/oauth2/) to find more about how to get consent from the user and how to retrieve an access token. 
+
+Use ``AvatarService`` to upload an avatar.
+
+```swift
+import Gravatar
+
+// [...]
+
+let service = AvatarService()
+let image: UIImage = // image of choice from the user
+let accessToken = // WordPress.com OAuth2 access token 
+do {
+   try await service.upload(image, email: Email("[email protected]"), accessToken: accessToken)
+} catch {
+    // handle error
+}
+
+``

Sources/Gravatar/Gravatar.docc/4. FetchingProfile.md

@@ -0,0 +1,43 @@
+#  Fetching Profile Information
+
+Fetch a public Gravatar profile. 
+
+Use ``ProfileService`` to fetch profile information.
+
+```swift
+import Gravatar
+
+// [...]
+
+Task {
+    await fetchProfile(with: "[email protected]")
+}
+
+func fetchProfile(with email: String) async {
+    let service = ProfileService()
+
+    do {
+        let profile = try await service.fetch(with: .email(email))
+        updateUI(with: profile)
+    } catch {
+        print(error)
+    }
+}
+
+@MainActor
+func updateUI(with profile: Profile) {
+    /// Update UI elements...
+}
+```
+
+#### Getting full Profile information and better rate limits
+
+Follow the steps in the [REST API documentation](https://docs.gravatar.com/api/profiles/rest-api/) to create a Gravatar API key. You can use some features without an API Key, but you’ll receive limited information, and stricter rate limits may apply. So we highly encourage you to create one in the [developer portal](https://gravatar.com/developers/).
+
+Use the ``Configuration`` class to set an api key, which will be used to authorise the request.
+
+```swift
+await Configuration.shared.configure(with: apiKey)
+```
+
+See ``Profile`` to know which fields are public, and which ones need `apiKey` authorization.