Merge pull request #97 from brown-ccv/docs-3.3

docs: Prep 3.3.x documentation

docusaurus.config.js

@@ -24,13 +24,14 @@ module.exports = {
 
           /**
            * Here we give a specific label to the current doc version. Note the old versions:
-           *    '3.1.x': { label: '3.0.0', path: '3.0.0' },
+           *    '3.2.x': { label: "3.2.x", path: "3.2.x" }
+           *    '3.1.x': { label: '3.1.x', path: '3.1.x' },
            *    '3.0.0': { label: '3.0.0', path: '3.0.0' },
            *    '2.x': { label: '2.x', path: '2.x' },
            *    '1.1.0': { label: '1.1.0', path: '1.1.0' },
            */
           lastVersion: "current",
-          versions: { current: { label: "3.2.x", path: "" } },
+          versions: { current: { label: "3.3.x", path: "" } },
         },
         blog: false, // Disable Docusaurus blog feature
       },

versioned_docs/version-3.2.x/deployments/firebase.mdx

@@ -0,0 +1,261 @@
+---
+id: firebase
+slug: /firebase
+title: Firebase
+description: Guide for connecting Honeycomb to a Firebase project
+---
+
+import firebaseActions from "/assets/firebase/firebase-actions.png";
+import firebaseConsoleSettings from "/assets/firebase/firebase-console-settings.png";
+import firebaseWebCredentials from "/assets/firebase/firebase-web-credentials.png";
+import firestoreCreateStudy from "/assets/firebase/firestore-create-study.png";
+import firestoreExampleStudy from "/assets/firebase/firestore-example-study.png";
+
+Honeycomb comes with methods and configurations to deploy tasks with [Firebase](https://firebase.google.com/). These tools make it possible to reach a wider audience by hosting your task online.
+
+## Setting up Firebase
+
+:::info
+Please have your PI contact [[email protected]](mailto:[email protected]) to create a Firebase project for your Honeycomb task before beginning.
+:::
+
+### Adding Products
+
+First we'll configure [Firebase Hosting](https://firebase.google.com/docs/hosting) and [Cloud Firestore](https://firebase.google.com/docs/firestore) on your project.
+
+1. Log in to Firebase with your Google account on the [Firebase console](https://console.firebase.google.com/).
+2. Navigate to your project from the console
+3. Register a new web app to your project ([Register your app](https://firebase.google.com/docs/web/setup#register-app))
+
+   :::note
+   We recommend giving your web app the same name as your task's repository
+   :::
+
+4. Add Firestore Database to your project ([Create a Cloud Firestore database](https://firebase.google.com/docs/firestore/quickstart#create))
+
+   :::note
+   Chose `production mode` for the starting mode and the default "Cloud Firestore Location"
+   :::
+
+The Firebase project is now fully set up! Now we'll connect your task to that project from your computer.
+
+### Installing the Command Line Interface
+
+The Firebase CLI is installed with the node package manager just like the rest of Honeycomb's dependencies. Be sure to log in with same account you used when logging into the console!
+
+```shell title="Install the Firebase CLI"
+npm install -g firebase-tools
+```
+
+```shell title="Login to Firebase"
+firebase login
+```
+
+_A "command not found" error usually indicates `firebase-tools` has not been installed correctly_
+
+### Connecting Your Firebase Project
+
+1. Change the default project name of your task in `.firebaserc`
+
+```json title=".firebaserc" showLineNumbers
+{
+  "projects": {
+    "default": "<your project name>"
+  }
+}
+```
+
+2. Copy the web app credentials from the Firebase console to the corresponding variables in `.env.firebase`
+
+   1. Return to your project on the [Firebase console](https://console.firebase.google.com/).
+   2. Navigate to your project setting
+
+      <img
+        src={firebaseConsoleSettings}
+        alt="Firebase project settings"
+      />
+
+   3. Scroll down and copy the auto-generated values from the Firebase console to the corresponding variables in the `.env.firebase` file in the `env` folder of your Honeycomb task repo
+
+      <img
+        src={firebaseWebCredentials}
+        alt="Firebase web credentials"
+      />
+      <br />
+      <br />
+
+      ```shell title="env/.env.firebase"
+      REACT_APP_FIREBASE="true"
+      REACT_APP_apiKey=
+      REACT_APP_authDomain=
+      REACT_APP_projectId=
+      REACT_APP_storageBucket=
+      REACT_APP_messagingSenderId=
+      REACT_APP_appId=
+      ```
+
+      _Additional variables may be present in the console, they do not need to be copied._
+
+3. Deploy the default [Firestore security rules](https://firebase.google.com/docs/firestore/security/get-started)
+
+```shell title="Deploy Firestore rules"
+firebase deploy --only firestore:rules
+```
+
+Your task is now connected to an initialized Firebase project!
+
+## Registering Studies
+
+:::caution
+This step must be followed **exactly**. See [Security Rules](#security-rules) for more information.
+:::
+
+1. Navigate to your Firestore Database in the [console](https://console.firebase.google.com/).
+2. Click "Start collection"
+3. Enter `registered_studies` for the collection id and click "next"
+4. Enter the id of your study for the document id
+5. Add a field named `registered_participants` with the type "array"
+6. Add the id of each study participant as a string inside the array
+
+<div style={{ textAlign: "center" }}>
+  <img
+    src={firestoreCreateStudy}
+    alt="Create a study"
+    style={{ maxHeight: "600px" }}
+  />
+</div>
+<br />
+
+The study should like this when you're finished:
+
+<img
+  src={firestoreExampleStudy}
+  alt="Example study"
+/>
+<br />
+<br />
+
+**Additional studies must be created inside the `registered_studies` collection**
+
+## Developing With Firebase
+
+_Two terminal windows must be used while developing for Firebase. See [here](https://code.visualstudio.com/docs/terminal/basics#_groups-split-panes) for instructions on splitting terminals in VSCode._
+
+```shell title="Run Honeycomb with Firebase Enabled"
+npm run dev:firebase
+```
+
+```shell title="Start the Firebase Emulators"
+npm run firebase:emulators:start
+```
+
+Honeycomb is now running in the browser and connected to data on an emulated instance of Firestore. It may be viewed at [http://localhost:4000/firestore](http://localhost:4000/firestore).
+
+:::info
+Honeycomb populates the Firestore emulators with the study `s1` and participant `p1`.
+:::
+
+## Deploying on Firebase
+
+Firebase deployments are handled automatically following [Continuous Integration Continuous Development (CI/CD)](ci_cd) practices using GitHub Actions. Here we will connect create custom actions that are connected to the task's Firebase project.
+
+Execute the following command to begin initializing Firebase hosting via GitHub actions. Be sure to follow the instructions below as the prompts appear.
+
+```shell title="Initialize Firebase hosting via Github actions"
+firebase init hosting:github
+```
+
+1. The window should log you in automatically. If not, follow the prompts to log in with the same account you used in the console.
+2. `<username>/<repository name>` refers to the name of your repository in Github. Be sure it's typed correctly!
+3. Enter `y` for the prompt "Set up the workflow to run a build script before every deploy?"
+4. Enter `npm install && npm run build:firebase` for the prompt "What script should be run before every deploy?"
+5. Enter `y` to overwrite the current workflow file
+6. Enter `y` for the prompt "Set up automatic deployment to your site's live channel when a PR is merged?"
+7. Enter `main` for the prompt "What is the name of the GitHub branch associated with your site's live channel?"
+8. Enter `y` to overwrite the current workflow file
+
+Firebase will update the files `firebase-hosting-pull-request.yml` and `firebase-hosting-merge.yml` inside the `.github/workflows/` directory. Ensure the correct run script is present in both files.
+
+<img
+  src={firebaseActions}
+  alt="Github actions created by firebase"
+/>
+
+## Managing Data
+
+Honeycomb ships with a CLI script for managing data in Firebase. A local service account must be created in order to use it.
+
+### Setting up a Service Account
+
+Service accounts are accounts that are not attached to a human user. They authorize access to a Firebase project without someone physically logging in online. We use a service account to give the download script access to the Firestore database automatically.
+
+1. Return to the project settings your project on the [Firebase console](https://console.firebase.google.com/).
+   <img
+     src={firebaseConsoleSettings}
+     alt="Firebase project settings"
+   />
+2. Click on the "Service accounts" tab
+3. Near the bottom, click "Generate new Private key" and "Generate Key"
+
+4. Rename the key `firebase-service-account.json` and move it to the root directory of your task. Be sure the file looks grayed out and is not picked up by git!
+
+:::danger
+A service account has total administrative access to ts Firebase project. The file and keys inside should never be shared and **never committed to GitHub.**
+:::
+
+### Using the CLI Script
+
+```bash title="Script Usage"
+npm run cli
+```
+
+The CLI script will guide you through the steps needed to manage your data appropriately:
+
+1. Whether you wish to download or delete data
+2. Entering the ID of a given study
+3. Entering the ID of a given participant on that study
+4. Selecting the sessions to download/delete
+   :::info
+
+   <kbd>SPACE</kbd> selects a single session and <kbd>A</kbd> toggles every session
+
+   :::
+
+:::note
+The download script will prompt you for where the data should be saved. It defaults to `.`, which is your current folder. The folder must exist before running the script.
+:::
+
+## Further Reading
+
+_The [Firebase Documentation](https://firebase.google.com/docs/emulator-suite) details its Emulator Suite in much greater detail._
+
+### Security Rules
+
+Honeycomb uses security rules to authenticate participants and studies for each task. By default participants must be registered to each study in order to complete the task.
+
+Firestore rules are defined in the `firestore.rules` file in the home directory. Note the highlighted lines:
+
+```firestore-security-rules title="firestore.rules" showLineNumbers
+rules_version = '2';
+service cloud.firestore {
+  //highlight-start
+  match /databases/{database}/documents {
+      match /participant_responses/{studyID}/participants/{participantID} {
+        allow create, read:
+        if participantID in get(/databases/$(database)/documents/registered_studies/$(studyID)).data.registered_participants;
+  //highlight-end
+        // ...
+      }
+    }
+}
+```
+
+Lines 3 and 4 indicate that Honeycomb attempts to connect to a document at `/databases/{database}/documents/participant_responses/{studyID}/participants/{participantID}` where `studyID` is a given study and `participantID` is a given participant within that study.
+
+Line 6 defines our rule - it must pass for Honeycomb to connect to the document. `participantID` must be found in an array called `registered_participants` inside of a document at `/databases/{database}/documents/registered_studies/{studyID}`.
+
+Line 5 indicates how Honeycomb can interact with that document. Note that Honeycomb cannot update or delete data! You must manually make these changes from the Firestore console.
+
+:::danger
+Firestore rules must define every match pattern in your project. Attempting to connect anywhere other than `/participant_responses/{studyID}/participants/{participantID}` will be automatically denied even if you add other collections to your database. This is why `firestore.rules` contains additional nested rules - these should be left alone.
+:::

versioned_docs/version-3.2.x/deployments/gh_pages.mdx

@@ -0,0 +1,17 @@
+---
+id: gh_pages
+slug: /gh_pages
+title: GitHub Pages
+description: Guide for deploying a task to GitHub Pages
+---
+
+The `.github/workflows/release.yml` workflow will automatically deploy your task to GitHub pages if you have it enabled for your repository. It uploads the built website to the `gh-pages` branch. You can then access your task at `<github user>.github.io/<repository>`.
+
+
+:::danger
+Session data is downloaded to the user's local machine upon completion of the experiment when using GH Pages. Because of this, GH Pages is not suitable for fully online experiments.
+:::
+
+### Setup
+
+Please follow the [GitHub documentation](https://docs.github.com/en/pages/quickstart) for setting up GH Pages on your repository and make sure the [publishing source](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) for your repository is configured for `gh-pages` branch.

versioned_docs/version-3.2.x/deployments/local_application.mdx

@@ -0,0 +1,33 @@
+---
+id: local_application
+slug: /local_application
+title: Local Application
+description: Guide for deploying a task as a local application
+---
+
+A major feature of Honeycomb is the ability to bundle JsPsych tasks into applications that can be run on any computer in a lab or clinic. Installers for these applications can be created for Windows, Mac, and Linux. The applications can be run without an internet connection, and do not require any additional software to be installed on the computer.
+
+Installers for these application can be created on demand and/or automatically when a new release is created. This is called "Continuous Deployment" - more information about Honeycomb's CI/CD workflow can be found here [here](ci_cd).
+
+## Creating a Release
+
+Follow the [GitHub documentation](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release) for creating a release.
+
+The tag should be in the format `vX.X.X` where `X.X.X` is the version number of the release. For example, if the release is version 1.0.0, the tag should be `v1.0.0`.
+
+:::warning
+Your release **must** included a new tag for the CI/CD workflow to work.
+:::
+
+## Running the task
+
+1. Navigate to the repository's "Releases" tab and select the tag you just created.
+2. Download the installer for your operating system.
+3. Double click the installer to run it. Follow the instructions to install the application.
+4. The application will automatically start after the first instillation.
+
+The executable does not require installation of any additional software!
+
+## Working with Data
+
+Data is automatically saved to a nested folder structure on the Desktop. Each session will be saved as its own `.json` file nested under the id of the study and participant.

versioned_docs/version-3.2.x/deployments/psiturk.mdx

@@ -0,0 +1,45 @@
+---
+id: psiturk
+slug: /psiturk
+title: PsiTurk
+description: Guide for the different deploying a task to PsiTurk
+---
+
+While honeycomb is optimized for use on a [local application](local_application), we added functionality for usage with [PsiTurk](https://psiturk.org/). The application will detect if it's being used in a Turk environment and will save the data to the default PsiTurk SQLite database.
+
+### Prebuilt version
+
+When GitHub Actions is run, a PsiTurk build will be created automatically, and can be downloaded from its artifacts. The workflows responsible for building the PsiTurk application are `.github/workflows/package.yml` and `.github/workflows/release.yml`. The first one has to be triggered manually, the latter is triggered when you tag a release.
+
+If this is all you need, the build instructions below can be skipped!
+
+### Build instructions
+
+To set up your PsiTurk project, we provide a script that does the conversion.
+PsiTurk is a Python package used to manage HITs in Mechanical Turk. Before using the provided script, install [PsiTurk](https://psiturk.org/).
+
+You'll need to follow these steps (the path to the PsiTurk project should be a directory you wish to be created):
+
+- Build the application: `npm run build`
+- Move to the `psiturkit` directory: `cd psiturkit`
+- If it's the first time you're running the script:
+
+  ```shell
+  ./psiturk-it -p <PATH_TO_NEW_PSITURK_PROJECT>
+  ```
+
+- To update an existing PsiTurk project (the path to the PsiTurk project should already exist from the previous steps):
+
+  ```shell
+  ./psiturk-it -U -p <PATH_TO_NEW_PSITURK_PROJECT>
+  ```
+
+### Running PsiTurk
+
+After that, just navigate to your newly created PsiTurk project directory.
+
+```shell
+shell> psiturk # start psiturk
+psiturk> server on # start server
+psiturk> debug # enter debug mode
+```