Researcher Documentation (#32)

* Set up mkdocs

* Add markdown files

* move to mocros plugin

* Format changes

* Finish parameters table for surveys

* Add strict to build

* Add validation, git repo url, and exclude docs to config

* Link to change log wasn't working

* Grammar mistake in record docs

.gitignore

@@ -2,4 +2,5 @@ node_modules
 dist
 coverage
 Procfile
-.env
+.env
+site

makefile

@@ -0,0 +1,12 @@
+serve: poetry
+	poetry run mkdocs serve
+
+build: poetry
+	poetry run mkdocs build --strict
+
+poetry:
+	poetry install --no-root --sync
+
+clean:
+	rm -rf ./site $(shell poetry env info -p)
+

mkdocs.yml

@@ -0,0 +1,27 @@
+site_name: CHS jsPsych
+docs_dir: ./packages
+repo_url: https://github.com/lookit/lookit-jspsych
+
+nav:
+  - Home: index.md
+  - CHS's initJsPsych: lookit-initjspsych/README.md
+  - Data: data/README.md
+  - Record: record/README.md
+  - Surveys: surveys/README.md
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn
+  anchors: warn
+exclude_docs: |
+  node_modules
+  lookit-initjspsych/CHANGELOG.md
+theme:
+  name: mkdocs
+  color_mode: auto
+  user_color_mode_toggle: auto
+plugins:
+  - search
+  - macros
+extra:
+  jsPsych: https://www.jspsych.org/7.3/

packages/data/README.md

@@ -0,0 +1,28 @@
+# Data
+
+This package will do the following:
+
+- Load data to be accessed while experiment is running.
+- Move data to and from CHS's API.
+- Move video content from the client computer to cloud storage.
+
+## Load
+
+When an experiment begins, some data will be loaded for use during the experiment. This function is called before an experiment is ran and doesn't need to be called again.
+
+```javascript
+await chsData.load(responseUuid);
+```
+
+Once this data has been loaded, it can be accessed on the `window` interface. The data should be structured as follows:
+
+```javascript
+window.chs = {
+  study,
+  child,
+  pastSessions,
+  response,
+};
+```
+
+For example, child information can be accessed at `window.chs.child` and can be used within your experiment.

packages/index.md

@@ -0,0 +1,9 @@
+# CHS Custom jsPsych Plugins And Extensions
+
+This documentation will provide explanations and use cases for the packages written by CHS for the jsPsych experiment runner.
+
+If you're just starting out, a great place to start would be with [jsPsych's documentation]({{ jsPsych }}). It's well written and will provide the majority of what one would need to know to create an experiment.
+
+## Developer Documentation
+
+Documentation for developers can be found in the [REAME](https://github.com/lookit/lookit-jspsych) for the monorepo.

packages/lookit-initjspsych/README.md

@@ -0,0 +1,18 @@
+# CHS's initJsPsych
+
+[Version History](https://github.com/lookit/lookit-jspsych/blob/main/packages/lookit-initjspsych/CHANGELOG.md)
+
+This package contains the repackaging of jsPsych's initjsPsych function. We needed to give ourselves the ability to do two things:
+
+- Validate the trial timeline.
+- Record trial data to CHS's API.
+
+## chsInitJsPsych
+
+This function will make available `initJsPsych()` and it can be expected to operate as the original.
+
+```javascript
+initJsPsych = chsInitJsPsych(responseUuid);
+```
+
+The above code is already placed into the experiment before your code. For transparency, you can always find `chsInitJsPsych()` on [npmjs](https://www.npmjs.com/package/@lookit/lookit-initjspsych?activeTab=code), [github](https://github.com/lookit/lookit-jspsych/tree/main/packages/lookit-initjspsych/src), and [unpkg](https://unpkg.com/browse/@lookit/lookit-initjspsych/src/). Please feel free to reach out with any questions or concerns.

packages/record/README.md

@@ -0,0 +1,85 @@
+# Record
+
+This package contains the plugins and extensions to record audio and/or video of either a single trial or multiple trials.
+
+## Initialize Camera
+
+To record video, you will have to add a trial that allows the user to give permissions and select the correct camera.
+
+```javascript
+const initCamera = { type: jsPsychInitializeCamera };
+```
+
+To enable audio you will have to set the `include_audio` parameter.
+
+```javascript
+const initCamera = { type: jsPsychInitializeCamera, include_audio: true };
+```
+
+See [jsPsych's initialize-camera]({{ jsPsych }}plugins/initialize-camera/#initialize-camera) docs for more information.
+
+## Intialize Microphone
+
+To record audio, just as with video, you will have to add a trial.
+
+```javascript
+const initMicrophone = { type: jsPsychInitializeMicrophone };
+```
+
+See [jsPsych's initialize-microphone]({{ jsPsych }}plugins/initialize-microphone/#initialize-microphone) docs for more information.
+
+## Trial Recording
+
+To record a single trial, you will have to first load the extension in `initJsPsych`.
+
+```javascript
+const jsPsych = initJsPsych({
+  extensions: [{ type: chsRecord.TrialRecordExtension }],
+});
+```
+
+Next, initialize the camera/microphone as described above. For now, we'll use the camera initialization. Add trial recording to the extensions parameter of the trial that needs to be recorded. Any trial you design can be recorded by add this extension.
+
+```javascript
+const trialRec = {
+  // ... Other trial paramters ...
+  extensions: [{ type: chsRecord.TrialRecordExtension }],
+};
+```
+
+Finally, insert the trials into the timeline.
+
+```javascript
+jsPsych.run([initCamera, trialRec]);
+```
+
+## Session Recording
+
+You might prefer to record across multiple trials in a study session. This can be done by using trials created with the start and stop recording plugins. This gives a bit of flexibility over which of the study trials are recorded.
+
+To record a study session, create the start and stop recording trials.
+
+```javascript
+const startRec = { type: chsRecord.StartRecordPlugin };
+const stopRec = { type: chsRecord.StopRecordPlugin };
+```
+
+Next, create the trials that you would like to be recorded.
+
+```javascript
+const morning = {type: jsPsychHtmlKeyboardResponse, stimulus: "Good morning!"};
+const evening = {type: jsPsychHtmlKeyboardResponse stimulus: "Good evening!"};
+const night = { type: jsPsychHtmlKeyboardResponse, stimulus: "Good night!" };
+```
+
+Lastly, add these trials to the timeline.
+
+```javascript
+jsPsych.run([initCamera, startRec, morning, evening, night, stopRec]);
+```
+
+It's possible to record only some of the trials. This can be done by moving the stop or start recording trials within the timeline.
+
+```javascript
+jsPsych.run([initCamera, startRec, morning, evening, stopRec, night]);
+```

packages/surveys/README.md

@@ -0,0 +1,33 @@
+# Surveys
+
+This package contains the custom surveys provided by CHS for jsPsych studies. These surveys are built off of the very nice [jsPsych Survey plugin]({{ jsPsych }}plugins/survey/).
+
+## Consent Survey
+
+The Consent Survey will will give you two things out of the box:
+
+- The API Response flags for `survey_consent` and `completed_consent_frame` will be set when the survey is completed.
+- Support for Markdown will be added.
+
+```javascript
+const consentSurvey = { type: chsSurveys.consent };
+```
+
+Other than that, the rest of the survey is entirely designed by you. Please refer to [jsPsych's Documentation]({{ jsPsych }}plugins/survey/) for the full explanation on how to use their plugin.
+
+## Exit Survey
+
+Unlike the consent survey, this survey is already designed with a few parameters for you to adjust to suite your study.
+
+```javascript
+const exitSurvey = { type: chsSurveys.exit };
+```
+
+### Parameters
+
+| Parameter                     | Type    | Default Value | Description                                              |
+| ----------------------------- | ------- | ------------- | -------------------------------------------------------- |
+| show_databrary_options        | boolean | true          | Show question about sharing collected data on Databrary. |
+| include_withdrawal_example    | boolean | true          | Include an example in withdrawal question text.          |
+| private_level_only            | boolean | false         | Only show "private" on use of media question.            |
+| additional_video_privacy_text | string  | ""            | Add custom video privacy text to privacy question.       |