Update Documentation in Conformance to the Documentation Guide (#17)

<!--

This source file is part of the Stanford Spezi open-source project

SPDX-FileCopyrightText: 2022 Stanford University and the project authors
(see CONTRIBUTORS.md)

SPDX-License-Identifier: MIT

-->

# Update Documentation in Conformance to the Documentation Guide

## ♻️ Current situation & Problem

Addresses #11.

By submitting creating this pull request, you agree to follow our [Code
of
Conduct](https://github.com/StanfordSpezi/.github/blob/main/CODE_OF_CONDUCT.md)
and [Contributing
Guidelines](https://github.com/StanfordSpezi/.github/blob/main/CONTRIBUTING.md):
- [X] I agree to follow the [Code of
Conduct](https://github.com/StanfordSpezi/.github/blob/main/CODE_OF_CONDUCT.md)
and [Contributing
Guidelines](https://github.com/StanfordSpezi/.github/blob/main/CONTRIBUTING.md).

---------

Co-authored-by: Paul Schmiedmayer <[email protected]>

.github/workflows/build-and-test.yml

@@ -23,12 +23,6 @@ jobs:
       artifactname: SpeziContact.xcresult
       runsonlabels: '["macOS", "self-hosted"]'
       scheme: SpeziContact
-  build:
-    name: Build Swift Package on Xcode 14
-    uses: StanfordSpezi/.github/.github/workflows/xcodebuild-or-fastlane.yml@v2
-    with:
-      runsonlabels: '["macos-13"]'
-      scheme: SpeziContact
   buildandtestuitests:
     name: Build and Test UI Tests
     uses: StanfordSpezi/.github/.github/workflows/xcodebuild-or-fastlane.yml@v2

README.md

@@ -16,14 +16,74 @@ SPDX-License-Identifier: MIT
 [![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2FStanfordSpezi%2FSpeziContact%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/StanfordSpezi/SpeziContact)
 [![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2FStanfordSpezi%2FSpeziContact%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/StanfordSpezi/SpeziContact)
 
-The Spezi Contact module provides user interface components to display customizable contact information in an application.
+Views to display contact information.
+
+## Overview
+
+The Spezi Contact Swift Package provides views and infrastructure to display contact information in an application.
+
+| ![Screenshot showing a ContactsList rendered within the Spezi Template Application.](Sources/SpeziContact/SpeziContact.docc/Resources/Overview.png#gh-light-mode-only) ![Screenshot showing a ContactsList rendered within the Spezi Template Application.](Sources/SpeziContact/SpeziContact.docc/Resources/Overview~dark.png#gh-dark-mode-only) |
+ |:---:|
+ | A [`ContactsList`](https://swiftpackageindex.com/stanfordspezi/spezicontact/documentation/spezicontact/contactslist) rendered in the Spezi Template Application. |
+
+## Setup
+
+### Add Spezi Contact as a Dependency
+
+You need to add the Spezi Contact Swift package to
+[your app in Xcode](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app#) or
+[Swift package](https://developer.apple.com/documentation/xcode/creating-a-standalone-swift-package-with-xcode#Add-a-dependency-on-another-Swift-package).
+
+## Example
+
+The Contact module enables displaying contact information in an application. 
+Information can be encoded in [`Contact`](https://swiftpackageindex.com/stanfordspezi/spezicontact/documentation/spezicontact/contact) and [`ContactOption`](https://swiftpackageindex.com/stanfordspezi/spezicontact/documentation/spezicontact/contactoption) to configure the contact views.
+The [`ContactView`](https://swiftpackageindex.com/stanfordspezi/spezicontact/documentation/spezicontact/contactview) and [`ContactsList`](https://swiftpackageindex.com/stanfordspezi/spezicontact/documentation/spezicontact/contactslist) can display the contact information in a card-like layout and list.
+
+The following example shows how [`Contact`](https://swiftpackageindex.com/stanfordspezi/spezicontact/documentation/spezicontact/contact)s can be created to encode an individual's contact information and displayed in a [`ContactsList`](https://swiftpackageindex.com/stanfordspezi/spezicontact/documentation/spezicontact/contactslist) within a SwiftUI [`View`](https://developer.apple.com/documentation/swiftui/view).
+
+```swift
+import SpeziContact
+import SwiftUI
+
+
+struct ContactsExample: View {
+    let contact = Contact(
+        image: Image(systemName: "figure.wave.circle"),
+        name: PersonNameComponents(givenName: "Leland", familyName: "Stanford"),
+        title: "Founder",
+        description: """
+        Leland Stanford is the founder of Stanford University.
+        """,
+        organization: "Stanford University",
+        address: {
+            let address = CNMutablePostalAddress()
+            address.country = "USA"
+            address.state = "CA"
+            address.postalCode = "94305"
+            address.city = "Stanford"
+            address.street = "450 Serra Mall"
+            return address
+        }(),
+        contactOptions: [
+            .call("+1 (650) 123-4567"),
+            .text("+1 (650) 123-4567"),
+            .email(addresses: ["[email protected]"], subject: "Hi!")
+        ]
+    )
+
+    var body: some View {
+        ContactsList(contacts: [contact])
+    }
+}
+```
 
 For more information, please refer to the [API documentation](https://swiftpackageindex.com/StanfordSpezi/SpeziContact/documentation).
 
 
 ## The Spezi Template Application
 
-The [Spezi Template Application](https://github.com/StanfordSpezi/SpeziTemplateApplication) provides a great starting point and example using the `SpeziContact` module.
+The [Spezi Template Application](https://github.com/StanfordSpezi/SpeziTemplateApplication) provides a great starting point and example using the [`SpeziContact`](https://swiftpackageindex.com/stanfordspezi/spezicontact) module.
 
 
 ## Contributing

Sources/SpeziContact/Contact Views/ContactView.swift

@@ -12,7 +12,7 @@ import SpeziViews
 import SwiftUI
 
 
-/// A ``ContactView`` enables the display of contact information as defined by a ``Contact``.
+/// Display contact information as defined by a ``Contact``.
 public struct ContactView: View {
     private let contact: Contact
 

Sources/SpeziContact/Contact Views/ContactsList.swift

@@ -9,7 +9,7 @@
 import SwiftUI
 
 
-/// A ``ContactsList`` enables the display of different ``ContactView``s in a card-like style in a scroll view.
+/// Display different ``Contact``s in a card-like style in a scroll view.
 ///
 /// You pass multiple ``Contact``s to the ``ContactsList`` to populate its content: ``ContactsList/init(contacts:)``:
 /// ```swift

Sources/SpeziContact/Models/Contact.swift

@@ -10,7 +10,7 @@
 import SwiftUI
 
 
-/// A ``Contact`` encodes the contact information.
+/// Encodes the contact information.
 public struct Contact {
     let id = UUID()
     /// The name of the individual. Ideally provide at least a first and given name.

Sources/SpeziContact/Models/ContactOption.swift

@@ -10,7 +10,7 @@ import MessageUI
 import SwiftUI
 
 
-/// A ``ContactOption`` encodes a way to get in contact with an individual and usually connected to a ``Contact``.
+/// Customizable way to get in contact with an individual and usually connected to a ``Contact``.
 public struct ContactOption {
     let id = UUID()
     /// The image representing the ``ContactOption`` in the user interface.

Sources/SpeziContact/SpeziContact.docc/Resources/Overview.png.license

@@ -0,0 +1,5 @@
+This source file is part of the Stanford Spezi open-source project
+
+SPDX-FileCopyrightText: 2022 Stanford University and the project authors (see CONTRIBUTORS.md)
+
+SPDX-License-Identifier: MIT

Sources/SpeziContact/SpeziContact.docc/Resources/Overview~dark.png.license

@@ -0,0 +1,5 @@
+This source file is part of the Stanford Spezi open-source project
+
+SPDX-FileCopyrightText: 2022 Stanford University and the project authors (see CONTRIBUTORS.md)
+
+SPDX-License-Identifier: MIT

Sources/SpeziContact/SpeziContact.docc/SpeziContact.md

@@ -12,7 +12,28 @@ SPDX-License-Identifier: MIT
 
 Views to display contact information.
 
-## Contact
+
+## Overview
+
+The Spezi Contact Swift Package provides views and infrastructure to display contact information in an application.
+
+@Row {
+    @Column {
+        @Image(source: "Overview", alt: "Screenshow showing a ContactsList rendered within the Spezi Template Application.") {
+            A ``ContactsList`` rendered in the Spezi Template Application.
+        }
+    }
+}
+
+## Setup
+
+### Add Spezi Contact as a Dependency
+
+You need to add the Spezi Mock Web Service Swift package to
+[your app in Xcode](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app#) or
+[Swift package](https://developer.apple.com/documentation/xcode/creating-a-standalone-swift-package-with-xcode#Add-a-dependency-on-another-Swift-package).
+
+## Example
 
 The Contact module enables displaying contact information in an application. 
 Information can be encoded in ``Contact`` and ``ContactOption`` to configure the contact views.
@@ -21,6 +42,10 @@ The ``ContactView`` and ``ContactsList`` can display the contact information in
 The following example shows how ``Contact``s can be created to encode an individual's contact information and displayed in a ``ContactsList`` within a SwiftUI View.
 
 ```swift
+import SpeziContact
+import SwiftUI
+
+
 struct ContactsExample: View {
     let contact = Contact(
         image: Image(systemName: "figure.wave.circle"),
@@ -66,5 +91,5 @@ The contact views that can be used to display contact information.
 
 Use the ``Contact`` and ``ContactOption`` to configure the contact views.
 
-- ``Contact/Contact``
+- ``Contact``
 - ``ContactOption``