Documentation & Setup Improvements (#59)

# Documentation & Setup Improvements


## ⚙️ Release Notes 
- Adds a DocC-based Documentation to host articles and
inline-documentation about different parts of the template application.
- Adds a setup script to automatically install all the necessary tools
and software elements to use the Spezi Template Application.
- Adds DocC articles to address part of #55:
   -  Setup your development environment
   - Change the template application to fit your project needs
   - Modify the application and point to relevant Spezi Modules


## 📝 Code of Conduct & Contributing Guidelines 

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).

.firebaserc.license

@@ -1,4 +1,4 @@
-This source file is part of the Stanford Spezi Template Application project
+This source file is part of the Stanford Spezi Template Application open-source project
 
 SPDX-FileCopyrightText: 2022 Stanford University and the project authors (see CONTRIBUTORS.md)
 

.github/workflows/beta-deployment.yml

@@ -1,5 +1,5 @@
 #
-# This source file is part of the Stanford Spezi Template Application project
+# This source file is part of the Stanford Spezi Template Application open-source project
 #
 # SPDX-FileCopyrightText: 2023 Stanford University
 #

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

@@ -1,5 +1,5 @@
 #
-# This source file is part of the Stanford Spezi Template Application project
+# This source file is part of the Stanford Spezi Template Application open-source project
 #
 # SPDX-FileCopyrightText: 2023 Stanford University
 #

.github/workflows/documentation-deployment.yml

@@ -0,0 +1,61 @@
+#
+# This source file is part of the Stanford Spezi open-source project
+#
+# SPDX-FileCopyrightText: 2023 Stanford University and the project authors (see CONTRIBUTORS.md)
+#
+# SPDX-License-Identifier: MIT
+#
+
+name: Documentation Deployment
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  deploydocs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: macos-13
+    steps:
+      - uses: actions/checkout@v4
+      - uses: maxim-lobanov/setup-xcode@v1
+        with:
+          xcode-version: latest-stable
+      - name: Check environment
+        run: |
+          xcodebuild -version
+          swift --version
+          echo "env.selfhosted: ${{ env.selfhosted }}"
+      - name: Build DocC
+        run: |
+          xcodebuild docbuild -scheme TemplateApplication \
+            -derivedDataPath .derivedData \
+            -destination 'generic/platform=iOS' \
+            -skipPackagePluginValidation \
+            CODE_SIGN_IDENTITY=""  \
+            CODE_SIGNING_REQUIRED=NO
+          $(xcrun --find docc) process-archive \
+            transform-for-static-hosting .derivedData/Build/Products/Debug-iphoneos/TemplateApplication.doccarchive \
+            --hosting-base-path SpeziTemplateApplication \
+            --output-path .docs
+          echo "<script>window.location.href += \"/documentation/templateapplication\"</script>" > .docs/index.html
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: '.docs'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/monthly-markdown-link-check.yml.yml

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

.gitignore

@@ -1,5 +1,5 @@
 #
-# This source file is part of the Stanford Spezi Template Application project
+# This source file is part of the Stanford Spezi Template Application open-source project
 #
 # SPDX-FileCopyrightText: 2023 Stanford University
 #
@@ -11,6 +11,7 @@
 .swiftpm
 .derivedData
 .build
+.docs
 !TemplateApplication.xcodeproj
 
 # IDE related folders
@@ -41,4 +42,7 @@ firebase-debug.log*
 firebase-debug.*.log*
 
 # Firebase cache
-.firebase/
+.firebase/
+
+# Swift Package List
+TemplateApplication/package-list.json

.swiftlint.yml

@@ -1,5 +1,5 @@
 #
-# This source file is part of the Stanford Spezi Template Application project
+# This source file is part of the Stanford Spezi Template Application open-source project
 #
 # SPDX-FileCopyrightText: 2023 Stanford University
 #

CITATION.cff

@@ -1,5 +1,5 @@
 #
-# This source file is part of the Stanford Spezi Template Application project
+# This source file is part of the Stanford Spezi Template Application open-source project
 #
 # SPDX-FileCopyrightText: 2023 Stanford University
 #

CONTRIBUTORS.md

@@ -1,6 +1,6 @@
 <!--
 
-This source file is part of the Stanford Spezi Template Application project
+This source file is part of the Stanford Spezi Template Application open-source project
 
 SPDX-FileCopyrightText: 2023 Stanford University
 

Gemfile

@@ -1,5 +1,5 @@
 #
-# This source file is part of the Stanford Spezi Template Application project
+# This source file is part of the Stanford Spezi Template Application open-source project
 #
 # SPDX-FileCopyrightText: 2023 Stanford University
 #

Gemfile.lock.license

@@ -1,5 +1,5 @@
 
-This source file is part of the Stanford Spezi Template Application project
+This source file is part of the Stanford Spezi Template Application open-source project
 
 SPDX-FileCopyrightText: 2023 Stanford University
 

README.md

@@ -1,6 +1,6 @@
 <!--
 
-This source file is part of the Stanford Spezi Template Application project
+This source file is part of the Stanford Spezi Template Application open-source project
 
 SPDX-FileCopyrightText: 2023 Stanford University
 
@@ -15,126 +15,36 @@ SPDX-License-Identifier: MIT
 [![DOI](https://zenodo.org/badge/589846478.svg)](https://zenodo.org/badge/latestdoi/589846478)
 
 This repository contains the Spezi Template Application.
-It demonstrates using the [Spezi](https://github.com/StanfordSpezi/Spezi) framework template and builds on top of the [Stanford Biodesign Digital Health Template Application](https://github.com/StanfordBDHG/TemplateApplication).
+It demonstrates using the [Spezi](https://github.com/StanfordSpezi/Spezi) ecosystem and builds on top of the [Stanford Biodesign Digital Health Template Application](https://github.com/StanfordBDHG/TemplateApplication).
 
 > [!NOTE] 
 > Do you want to try out the Spezi Template Application? You can download it to your iOS device using [TestFlight](https://testflight.apple.com/join/ipEezBY1)!
 
 
-## Application Structure
+## Application Content
 
-The Spezi Template Application uses a modularized structure using the [Spezi modules](https://swiftpackageindex.com/StanfordSpezi) enabled by the Swift Package Manager.
+The following screenshots show a wide variety of features based on Spezi Modules that are part of the Spezi Template Application.
 
-The application uses [HL7 FHIR](https://www.hl7.org/fhir/) and the Spezi [`FHIR` module](https://github.com/StanfordSpezi/SpeziFHIR) to provide a common standard to encode data gathered by the application as defined in the Spezi [`Standard`](https://swiftpackageindex.com/stanfordspezi/spezi/documentation/spezi/standard) found in the application.
-You can learn more about the Spezi standards-based software architecture in the [Spezi documentation](https://swiftpackageindex.com/stanfordspezi/spezi/documentation/spezi).
+|![A screen displaying welcome information.](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Onboarding/Welcome.png#gh-light-mode-only) ![A screen displaying welcome information.](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Onboarding/Welcome~dark.png#gh-dark-mode-only)|![A screen showing an overview of the modules used in the Spezi Template Application.](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Onboarding/InterestingModules.png#gh-light-mode-only) ![A screen showing an overview of the modules used in the Spezi Template Application.](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Onboarding/InterestingModules~dark.png#gh-dark-mode-only)|![A screen displaying the consent view.](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Onboarding/Consent.png#gh-light-mode-only) ![A screen displaying the consent view.](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Onboarding/Consent~dark.png#gh-dark-mode-only)
+|:--:|:--:|:--:|
+|Welcome View|Interesting Modules|Consent Signature|
 
+|![HealthKit Onboarding Flow](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Onboarding/HealthKitAccess.png#gh-light-mode-only) ![HealthKit Onboarding Flow](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Onboarding/HealthKitAccess~dark.png#gh-dark-mode-only)|![Permissions screen of the HealthKit framework](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Onboarding/HealthKitSheet.png#gh-light-mode-only) ![Permissions screen of the HealthKit framework](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Onboarding/HealthKitSheet~dark.png#gh-dark-mode-only)|![A screen displaying the Scheduler UI.](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Schedule/Schedule.png#gh-light-mode-only) ![A screen displaying the Scheduler UI.](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Schedule/Schedule~dark.png#gh-dark-mode-only)
+|:--:|:--:|:--:|
+|HealthKit Access|Granular HealthKit Share Control|Schedule Tasks|
 
-## Build and Run the Application
+|![Onboarding screen showing the Notifications permission screen.](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Schedule/Notifications.png#gh-light-mode-only) ![Onboarding screen showing the Notifications permission screen.](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Schedule/Notifications~dark.png#gh-dark-mode-only)|![A screen showing a questionnaire using ResearchKit.](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Schedule/Questionnaire.png#gh-light-mode-only) ![A screen showing a questionnaire using ResearchKit.](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Schedule/Questionnaire~dark.png#gh-dark-mode-only)|![The scheduler screen showing the completed UI](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Schedule/ScheduleComplete.png#gh-light-mode-only) ![The scheduler screen showing the completed UI](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Schedule/ScheduleComplete~dark.png#gh-dark-mode-only)
+|:--:|:--:|:--:|
+|Trigger Local Notifications|Display Questionnaires|Keep Track of Tasks|
 
-You can build and run the application using [Xcode](https://developer.apple.com/xcode/) by opening up the **TemplateApplication.xcodeproj**.
-
-
-### Get Started without Firebase
-
-You can start using the application without any additional installations if you use the ``--disableFirebase`` feature flag, enabled by default when opening the Xcode project. The login and account setup is skipped in this configuration.
-
-
-### Firebase Setup
-
-The application also provides a [Firebase Firestore](https://firebase.google.com/docs/firestore)-based data upload and [Firebase Authentication](https://firebase.google.com/docs/auth) login & sign-up.
-It is required to have the [Firebase Emulator Suite](https://firebase.google.com/docs/emulator-suite) to be up and running to use these features to build and test the application locally. Please follow the [installation instructions](https://firebase.google.com/docs/emulator-suite/install_and_configure). 
+|![A screen displaying the Contact UI.](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Context/Contacts.png#gh-light-mode-only) ![A screen displaying the Contact UI.](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Context/Contacts~dark.png#gh-dark-mode-only)|![License information to list all used Swift Packages](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Context/License.png#gh-light-mode-only) ![License information to list all used Swift Packages](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Context/License~dark.png#gh-dark-mode-only)|![User Interface of the Mock Web Service](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Context/Request.png#gh-light-mode-only) ![User Interface of the Mock Web Service](TemplateApplication/Supporting%20Files/TemplateApplication.docc/Resources/Context/Request~dark.png#gh-dark-mode-only)
+|:--:|:--:|:--:|
+|Contact Information|License Information|Mock Web Service Requests|
 
 > [!NOTE] 
-> You do not have to make any modifications to the Firebase configuration, login into the `firebase` CLI using your Google account, or create a project in Firebase to run, build, and test the application!
-
-Startup the [Firebase Emulator Suite](https://firebase.google.com/docs/emulator-suite) using
-```
-$ firebase emulators:start
-```
-
-After the emulators have started up, you can run the application in your simulator to build, test, and run the application and see the results show up in Firebase.
-
-If you want to connect your project to a development or production Firebase cloud project, you can provide your [`GoogleService-Info.plist`](https://firebase.google.com/docs/ios/setup) in a base 64 representation in the [GitHub secrets](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions) (`GOOGLE_SERVICE_INFO_PLIST_BASE64`) of your project where it is picked up and loaded in the configured path setup in the [`beta-deployment.yml`](.github/workflows/beta-deployment.yml) [GitHub Action](https://docs.github.com/en/actions) using the `googleserviceinfoplistpath` parameter that needs to be adapted to your project structure.
-
-You can generate a base 64 representation of a file after you [navigated into the folder](https://en.wikipedia.org/wiki/Cd_(command)#Usage) where you have downloaded your [`GoogleService-Info.plist`](https://firebase.google.com/docs/ios/setup) file to.
-```shell
-base64 -i GoogleService-Info.plist
-```
-
-> [!WARNING]  
-> We do **not recommend** to commit your Firebase secrets and configuration file to your project. While it can extract the file from the deployed application, we encourage open-source projects to make it clear to contributors to set up their own Firebase project.
-
-The deployment requires you to store your Google service account JSON credentials in a base 64 representation in the `GOOGLE_APPLICATION_CREDENTIALS_BASE64`. You can learn more about how to generate the JSON in the [Firebase documentation](https://firebase.google.com/docs/app-distribution/authenticate-service-account). The service account must have the minimally required permissions (not the `Firebase App Distribution Admin` role) as documented at https://firebase.google.com/docs/projects/iam/roles-predefined for your deployment needs and setup.
-
-Be sure to update your `.firebaserc` project name and placeholder `GoogleService-Info.plist` project identifier to always reflect the name of your project and all security rules to reflect any changes in your application.
-
-
-### Other Configuration Options
-
-The application also includes the following feature flags that can be configured in the [scheme editor in Xcode](https://help.apple.com/xcode/mac/11.4/index.html?localePath=en.lproj#/dev0bee46f46) and selecting the **TemplateApplication** scheme, the **Run** configuration, and to switch to the **Arguments** tab to add, enable, disable, or remove the following arguments passed on launch:
-- ``--skipOnboarding``: Skips the onboarding flow to enable easier development of features in the application and to allow UI tests to skip the onboarding flow.
-- ``--showOnboarding``: Always show the onboarding when the application is launched. Makes it easy to modify and test the onboarding flow without the need to manually remove the application or reset the simulator.
-- ``--disableFirebase``: Disables the Firebase interactions, including the login/sign-up step and the Firebase Firestore upload.
-- ``--useFirebaseEmulator``: Defines if the application should connect to the local Firebase emulator. Always set to true when using the iOS simulator.
-
-
-## Template Onboarding Flow
-
-The onboarding contains different steps.
-It uses the [**Spezi Onboarding** module](https://github.com/StanfordSpezi/SpeziOnboarding) to display different onboarding-related views like the information about the application, a consent screen, and a screen to display a HealthKit consent view.
-
-<p float="left">
- <img width="250" alt="A screen displaying welcome information." src="Figures/TemplateOnboardingFlow/Welcome.png">
- <img width="250" alt="A screen showing an overview of the modules used in the Spezi Template application." src="Figures/TemplateOnboardingFlow/InterestingModules.png">
- <img width="250" alt="A screen displaying the consent view." src="Figures/TemplateOnboardingFlow/Consent.png">
- <img width="250" alt="A screen showing a view displaying the HealthKit access screen." src="Figures/TemplateOnboardingFlow/HealthKitAccess.png">
-</p>
-
-
-## Template Schedule
-
-The scheduler part of the application provides the functionality to schedule a recurring task and bind it to an action, e.g., displaying a questionnaire.
-It uses the [**Spezi Scheduler**](https://github.com/StanfordSpezi/SpeziScheduler) and [**Spezi Questionnaire**](https://github.com/StanfordSpezi/SpeziQuestionnaire) modules to schedule the tasks as defined in the `TemplateApplicationScheduler`.
-
-<p float="left">
- <img width="250" alt="A screen displaying the Scheduler UI." src="Figures/TemplateSchedule/Scheduler.png">
- <img width="250" alt="A screen showing a questionnaire using ResearchKit." src="Figures/TemplateSchedule/Questionnaire.png">
- <img width="250" alt="A screen displaying the Scheduler UI when the questionnaire is finished." src="Figures/TemplateSchedule/QuestionnaireFinished.png">
-</p>
-
-
-## Template Contacts
-
-The Contacts part of the application provides the functionality to display contact information in your application.
-It uses the [**Spezi Contacts** module](https://github.com/StanfordSpezi/SpeziContact) to use the contact-related views provided by Spezi.
-
-<p float="left">
- <img width="250" alt="A screen displaying the Contact UI." src="Figures/TemplateContacts/Contacts.png">
-</p>
-
-
-## Template Mock Data Storage Provider
-
-The mock upload view allows a developer to get an overview of the data synchronization between the application and a cloud storage provider.
-It is shown in the application when the ``--disableFirebase`` configuration flag is active.
-It uses the [**Spezi Mock Web Service** module](https://github.com/StanfordSpezi/SpeziMockWebService) to enable this functionality.
-
-<p float="left">
- <img width="250" alt="A screen displaying the list of Mock Data Storage Provider uploads." src="Figures/TemplateMockDataStorageProvider/TemplateMockDataStorageProviderList.png">
- <img width="250" alt="A screen displaying the detailed overview of one Mock Data Storage Provider upload." src="Figures/TemplateMockDataStorageProvider/TemplateMockDataStorageProviderDetail.png">
-</p>
-
-
-## Continuous Delivery Workflows
-
-The Spezi Template application includes continuous integration (CI) and continuous delivery (CD) setup.
-- Automatically build and test the application on every pull request before deploying it. If your organization doesn't have a self-hosted macOS runner modeled after the setup in the [StanfordBDHG ContinuousIntegration](https://github.com/StanfordBDHG/ContinousIntegration) setup, you will need to remove the `runsonlabels` arguments in the `build-and-test.yml` file to ensure that the build runs on the default macOS runners provided by GitHub.
-- An automated setup to deploy the application to TestFlight every time there is a new commit on the repository's main branch.
-- Ensure a coherent code style by checking the conformance to the SwiftLint rules defined in `.swiftlint.yml` on every pull request and commit.
-- Ensure conformance to the [REUSE Specification]() to property license the application and all related code.
-
-Please refer to the [Stanford Biodesign Digital Health Template Application](https://github.com/StanfordBDHG/TemplateApplication) and the [ContinuousDelivery Example by Paul Schmiedmayer](https://github.com/PSchmiedmayer/ContinousDelivery) for more background about the CI and CD setup for the Spezi Template Application.
+> You can find all the used Spezi Modules in the [Stanford Spezi GitHub Organization](https://github.com/StanfordSpezi).
 
+The [DocC documentation of the Spezi Template Application contains information on how to use the application as the basis for your Spezi-based application, run the application, and modify the application](https://stanfordspezi.github.io/SpeziTemplateApplication).
 
 ## Contributing