Feature/graphics (#1)

Add mermaid js action

---------

Co-authored-by: Timo Huber <timo.huber@econ.uzh.ch>

.devcontainer/Dockerfile

@@ -0,0 +1,30 @@
+FROM node:lts
+
+# Avoid warnings by switching to noninteractive
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Configure apt and install packages
+RUN apt-get update \
+  && apt-get -y install --no-install-recommends apt-utils dialog 2>&1 \
+  #
+  # Install git, process tools, lsb-release
+  && apt-get install -y wget git openssh-client iproute2 procps lsb-release zsh \
+  #
+  # Install oh-my-zsh
+  && wget https://github.com/robbyrussell/oh-my-zsh/raw/master/tools/install.sh -O - | zsh \
+  && cp ~/.oh-my-zsh/templates/zshrc.zsh-template ~/.zshrc \
+  #
+  # Clean up
+  && apt-get autoremove -y \
+  && apt-get clean -y \
+  && rm -rf /var/lib/apt/lists/* \
+  #
+  # Set time zone
+  && ln -sf /usr/share/zoneinfo/Europe/Zurich /etc/localtime
+
+# Install mermaid js dependencies
+RUN apt-get update \
+  && apt-get y install chromium
+
+# Switch back to dialog for any ad-hoc use of apt-get
+ENV DEBIAN_FRONTEND=dialog

.devcontainer/devcontainer.json

@@ -0,0 +1,29 @@
+{
+  "name": "Z-Pool Tool Documentation",
+  "build": {
+    "dockerfile": "Dockerfile"
+  },
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "terminal.integrated.profiles.linux": {
+          "zsh": {
+            "path": "/bin/zsh"
+          }
+        },
+        "terminal.integrated.defaultProfile.linux": "zsh",
+        "editor.formatOnSave": true
+      },
+      "extensions": [
+        "ritwickdey.LiveServer",
+        "yzhang.markdown-all-in-one"
+      ]
+    }
+  },
+  "mounts": [
+    "source=${localEnv:HOME}${localEnv:USERPROFILE}/.ssh,target=/root/.ssh,type=bind",
+    "source=${localEnv:HOME}${localEnv:USERPROFILE}/.gitconfig,target=/root/.gitconfig,type=bind",
+    "source=${localEnv:HOME}${localEnv:USERPROFILE}/.gitignore_global,target=/root/.gitignore_global,type=bind"
+  ],
+  "postCreateCommand": "yarn install"
+}

.github/workflows/jekyll-gh-pages.yml

@@ -28,6 +28,14 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+      - name: Generate mermaid diagrams
+        uses: addnab/docker-run-action@v3
+        with:
+          image: minlag/mermaid-cli:latest
+          options: -v ${{ github.workspace }}:/app -w /app
+          run: 
+            chmod +x /app/scripts/render-images.sh  
+            /app/scripts/render-images.sh  
       - name: Setup Pages
         uses: actions/configure-pages@v4
       - name: Build with Jekyll

.gitignore

@@ -1,4 +1,7 @@
 .DS_Store
+node_modules
 
 docs/_site/
-docs/.jekyll_cache
+docs/.jekyll_cache
+
+images/*

diagrams/online-studies.mmd

@@ -0,0 +1,14 @@
+sequenceDiagram
+    actor Contact
+    participant Pool
+    participant Survey Platform
+
+    Pool-)Contact: Invitation (3)
+    Contact->>Pool: Opens invitation link
+    activate Contact
+    Pool-)Survey Platform: Redirects contact to survey URL (4)
+    activate Survey Platform
+    Survey Platform--)Pool: Redirects contact back to callback URL (5)
+    deactivate Survey Platform
+    Pool->>Contact: Completes assignment and displays message (6)
+    deactivate Contact

docs/README.MD

@@ -9,3 +9,4 @@ This documentation is generated by GitHub Pages.
 The page uses the Jekyll theme `just-the-docs`. For more information, visit: https://just-the-docs.com/
 
 To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults
+

docs/best_practices/online_studies.md

@@ -0,0 +1,20 @@
+---
+layout: default
+title: Online Studies
+parent: Best Practices
+nav_order: 3
+---
+
+# Online Studies
+
+## Set up
+
+1. To create an online study, check the checkbox `Assignment without session` and provide the URL of your survey. This is where the contacts will be forwarded, when they start the survey.
+   The url parameter `callbackUrl` will be replaced by an URL on your pool to close the assignment, when the contact has finished the survey. A possible survey url could be: `https://uzhwwf.qualtrics.com/jfe/form/SV_123123?callback={callbackUrl}`
+2. Online studies are not tied to sessions. Therefore, you create a time window during which the contacts can participate in the study. If no time window is open at the moment, the matcher will not send any invitations.
+3. Create your filter and start sending invitations. Invited contacts will now be able to open the experiment detail page.
+4. When clicking on "start survey", an assignment will be created and the contact will be redirected to the rendered survey URL (in our example, this could be: `https://uzhwwf.qualtrics.com/jfe/form/SV_123123?callback=https://www.uast.uzh.ch/staging/experiments/559cca08-bc71-4665-834c-4c7dfd357707/submit/059fa14a-ff6b-4c40-b6d2-d9cbceb8a6c6`, where `{callbackUrl}` was replaced by the working callback URL belonging to the created assignment.)
+5. When the contact finished the survey, he/she should be redirected back to the callback url (more details)
+6. The `participated` flag of the assignment will be set and the `participation count` will be updated
+
+![online study workflow](../../images/online-studies.svg)

mermaidConfig.json

@@ -0,0 +1,9 @@
+{
+    "diagramMarginX": 20,
+    "diagramMarginY": 20,
+    "boxTextMargin": 5,
+    "noteMargin": 10,
+    "messageMargin": 35,
+    "mirrorActors": false
+  }
+

package.json

@@ -0,0 +1,15 @@
+{
+  "name": "pool-documentation",
+  "version": "1.0.0",
+  "main": "index.js",
+  "repository": "git@github.com:uzh/pool-documentation.git",
+  "author": "Timo Huber <timo.huber@econ.uzh.ch>",
+  "license": "MIT",
+  "dependencies": {
+    "@mermaid-js/mermaid-cli": "^10.9.1",
+    "mermaid": "^10.9.1"
+  },
+  "scripts": {
+    "mermaid": "./node_modules/.bin/mmdc -p puppeteer-config.json -i graphics/OnlineStudies.mmd -o images/OnlineStudies.png -b transparent"
+  }
+}

puppeteer-config.json

@@ -0,0 +1,6 @@
+{
+    "executablePath": "/usr/bin/chromium",
+    "args": [
+        "--no-sandbox"
+    ]
+}

scripts/render-images.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+input_dir="diagrams"
+output_dir="images"
+
+for file in "$input_dir"/*.mmd; do
+  base_name=$(basename "$file" .mmd)
+  ./node_modules/.bin/mmdc -p puppeteer-config.json -i "$file" -o "$output_dir/${base_name}.svg" -b transparent
+done
+
+echo "Rendering mermaid diagrams completed."