changed readme changed structure of docs, changed theme of docs, adde…

…d diagram

README.md

@@ -1,78 +1,11 @@
-<p align="center">
-  <a href="https://github.com/d3i-infra/feldspar">
-    <img width="40%" height="40%" src="./public/port_logo.svg">
-  </a>
-</p>
+# The data donation task
 
-# Data donation task for Next
-
-The data donation task is part of a research tool that enables researchers to collected digital trace data for academic research from participants in a secure, transparent, and privacy-preserving way.
-
-Data donation allows researchers to invite participants to share their data download packages (DDPs).
-A major challenge is however that DDPs potentially contain very sensitive data, and often not all data is needed to answer the specific research question under investigation.
-To circumvent these challenges, the following framework framework was developed:
-
-1. The research participant requests their personal DDP at the platform of interest.
-2. They download it onto their own personal device.
-3. By means of local processing (i.e. in the browser of the participant) only the features of interest to the researcher are extracted from that DDP.
-4. The participant inspects the extracted features after which they can consent (or decline) to donate.
-
-To allow for step 3 and 4 to take place the data donation task is. The data donation task is front end that guides participants through the data donation steps.
-The data donation task is primarily created to be used in conjunction with [Next](https://github.com/eyra/mono). 
+The data donation task is front end that guides participants through the data donation steps, used in conjunction with Next.
 Next is a software as a service platform developed by [Eyra](https://eyra.co/) to facilitate scientific research.
 
+## Documentation
 
-## How does the data donation task work?
-
-**The idea behind the data donation task**
-
-This data donation task repository contains in essence a toolkit with which you can build your own data donation flow. The donation flow is at the heart of the data donation task, and is at the core of a data donation study. 
-It is the step where the participant is actually going to donate their data.
-
-The data donation flow goes as follows:
-
-1. The participant goes to your data donation task app in a browser
-2. The participant is prompted to submit their data download package (DDP)
-3. A Python script you wrote, extracts the data you need for your research
-4. That data gets presented to the participant on screen. (The participant gets to interact with their data)
-5. The participants decides to donate and you receive the data 
-
-We opted for a toolkit approach because it offers several benefits:
-
-1. Every study requires unique elements for its participants, and a toolkit can facilitate the creation of this distinct experience.
-2. You can extract (and possibly aggregate) only the data you need for your study, which we believe is important in order to preserve the privacy of the participant and is often required by an ethical review board.
-
-
-**The design of the data donation task**
-
-The data donation task has reusable components (such as: a screen that prompts the participant to submit their DDP and a screen with tables that the participants need to review prior to donation) that you can use and combine/rearrange in creative ways to make your own study.
-These components are combined in a Python script that is created by the researcher or a research engineer.
-
-On a high level the script works as follows:
-
-1. The Python script determines which user interface (UI) component needs to be shown to the participant
-2. The participant interacts with the UI component on screen. Whenever the participant is done interacting with the UI component, the result of that interaction is returned to the script.
-3. The script handles the return result en determine the next UI component that the participant needs to see or interact with, go back to step 1 until the end of the donation flow.
-
-
-**Creating your own study**
-
-A researcher can implement their own data donation flow by altering a Python script included in this repository called [`script.py`](src/framework/processing/py/port/script.py).
-`script.py` has 2 different purposes:
-
-1. It determines the data donation flow. i.e. what screens (for example a file prompt) does the participant gets to see and when. 
-2. You can place functions here that extract the data you are interested in from the participants submission. Here is were Python really shines, you can use most data extraction methods you are familiar with! (As long as it's available in [Pyodide](https://pyodide.org/en/stable/))
-
-A typical script includes the following steps:
-
-1. Prompt the participant to submit a file
-2. Handling the submission from step 1. This is the step where you can extract the data you are interested in.
-3. The extracted data is presented on screen accompanied with a consent button. After consent is given, the data is sent to a storage location of the researcher (not included in the data donation task).
-
-A example such a script is included in this repo: [`script.py`](src/framework/processing/py/port/script.py).
-We recommend you use that script as starting point for your own data donation study.
-
-Check out the [documentation](https://d3i-infra.github.io/data-donation-task/) for a tutorial on how to start writing your own `script.py`.
+Here you can find the [documentation](https://d3i-infra.github.io/data-donation-task/) of this repository and tutorial articles to get you going.
 
 
 ## Installation of the data donation task
@@ -104,22 +37,6 @@ If the installation went correctly you should be greeted with a mock data donati
 For detailed installation instructions see the [documentation](https://d3i-infra.github.io/data-donation-task/).
 
 
-## Feldspar and Next
-
-The data donation task is primarily created to be used in conjunction with [Next](https://github.com/eyra/mono). Next is a software as a service platform developed by [Eyra](https://eyra.co/) to facilitate scientific research.
-The data donation task is a fork of [Feldspar](https://github.com/eyra/feldspar) with some extra functionalities added to it. Feldspar is a framework which can be used to build applications specifically for Next. An example of such an application is the data donation task which you can find in this repository. 
-
-For detailed information on how to deploy the data donation task with Next check the [documentation](https://d3i-infra.github.io/data-donation-task/).
-
-_Note_: The data donation task is only a *front end* to be used with Next. In order for it to be used in a live study it needs to be hosted with Next.
-The wiki will discuss the options you have for using the data donation task in an actual study.
-
-
-## Documentation
-
-Here you can find the [documentation](https://d3i-infra.github.io/data-donation-task/)
-
-
 ## Contributing
 
 We want to make contributing to this project as easy and transparent as possible, whether it's:
@@ -131,6 +48,7 @@ We want to make contributing to this project as easy and transparent as possible
 
 If you have any questions, find any bugs, or have any ideas, read how to contribute [here](https://github.com/eyra/port/blob/master/CONTRIBUTING.md).
 
+
 ## Citation
 
 If you use this repository in your research, please cite it as follows:

doc/source/api/index.rst

@@ -2,6 +2,6 @@ API Reference
 =============
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
    api.md

doc/source/conf.py

@@ -30,11 +30,20 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'piccolo_theme'
+html_theme = "sphinx_book_theme"
 html_static_path = ['_static']
 
-html_sidebars = {
-    '**': [
-        'globaltoc.html',
-    ]
+#html_sidebars = {
+#    '**': [
+#        'globaltoc.html',
+#    ]
+#}
+
+html_theme_options = {
+    "globaltoc_collapse": False,
+    "home_page_in_toc": True,
+    "repository_url": "https://github.com/d3i-infra/data-donation-task",
+    "use_repository_button": True,
 }
+
+html_title = "The data donation task"

doc/source/articles/creating-your-own-data-donation-task.md → doc/source/getting_started/creating-your-own-data-donation-task.md

@@ -1,63 +1,7 @@
-# Creating your own donation task
+# Creating your own data donation task
 
-The donation task is at the core of a data donation study. 
-It is the step where the participant is actually going to donate their data.
 
-The data donation task goes as follows:
-
-1. The participant goes to your data donation task app in a browser
-2. The participant is prompted to submit their data download package (DDP)
-3. A Python script you wrote, extracts the data you need for your research
-4. That data gets presented to the participant on screen
-5. The participants decides to donate and you receive the data 
-
-## Using the data donation task in a data donation study
-
-The data donation task needs to be used in together with Next. Next is the backend for the data donation task. With Next you can configure a data donation study: i.e. configure: 
-
-* Your data donation task
-* An information page
-* An informed consent page
-* A privacy policy
-* Instruction manuals for participants
-* Configure where the data should go
-* and more
-
-You can find more information on how to deploy a study in the wiki
-
-
-## How does the data donation task work?
-
-**The idea behind the data donation task**
-The data donation task repository is in essence a toolkit with which you can build your own custom data donation task.
-It is designed as a toolkit because researchers need to tailor the data donation task to their own interests; they interested in different DDPs and are interested in different data within those DDPs.
-
-This toolkit approach has several benefits:
-
-1. It allows for a bespoke experience for the participant
-2. You can only extract (and possibly aggregate) the data you need for you study, which we think is important in order to preserve the privacy of the participant and is often a requirement from your data steward/ethical review board
-
-These benefits come at the cost of added complexity compared to a one size fits all approach that extracts most or all data from the participant.
-
-**The design of the data donation task**
-The data donation task contains reusable components (such as: a screen that prompts the participant to submit their DDP and a screen with tables that the participants need to review prior to donation) that you can use and combine in creative ways to make your own study.
-These components are combined in a Python script that is created by the researcher. 
-
-On a high level the script works as follows:
-
-1. The Python script determines which user interface (UI) component needs to be shown to the participant
-2. Whenever the participant is done interacting with the UI component, the result of that interaction is returned to the script
-3. The script handles the return result en determine the next UI component that the participant needs to see or interact with, go back to step 1 until the end of the donation task
-
-**The architecture of the data donation task**
-The data donation task is a web application (build with [React](https://react.dev/) and [Pyodide](https://pyodide.org/en/stable/)) that completely runs in the browser of the participant. 
-The Python script and the UI components will run completely in the browser of the participant.
-Data is only sent to the server upon the participant clicking a consent button.
-
-
-## Start writing your first data donation task script
-
-After you have forked or cloned and installed this repository (see [instruction](https://github.com/d3i-infra/feldspar/wiki/Installation)) you can start creating your own donation task. 
+After you have forked or cloned and installed the repository you can start creating your own donation task. 
 
 You can create your own study by changing and/or adapting the code in the following directory `port/src/framework/processing/py/port/`
 This directory contains the following files:
@@ -155,7 +99,7 @@ def process(session_id: str):
 
 **The functions used in `process`**
 
-These are all the functions used in `process` together they make up `script.py`.
+These are all the functions used in `process` together they make up `script.py` (Click on the functions to expand)
 
 <details>
 <summary>extract_the_data_you_are_interested_in</summary>

doc/source/articles/deployment.md → doc/source/getting_started/deployment.md

@@ -14,18 +14,18 @@ As a researcher you can log in to Next and configure data donation study, this m
 
 After configuration participants can be sent to Next with a unique id in the url. This unique key id be used when storing the data, so you know who donated their data
 
-### Next as a paid service
+## Next as a paid service
 
 You can use Next as a paid service provided by [Eyra](https://eyra.co/). 
 Please contact Eyra if this is something you are interested in.
 
 
-### Self service Next (community version) on Surf Research Cloud
+## Self service Next (community version) on Surf Research Cloud
 
 Next is available as an offering on [Surf Research Cloud](https://www.surf.nl/en/services/surf-research-cloud) available for Researchers at Dutch universities and universities of applied sciences.
 This offering on Surf Research Cloud comes with no service or warranties. 
 
-#### Applying for an EINFRA grant
+### Applying for an EINFRA grant
 
 In order to use Surf Research Cloud you need credits. 
 
@@ -35,19 +35,19 @@ Dutch researchers can get credits on Surf Research Cloud by applying for an EINF
 2. Under "Apply for access" click "Small Compute applications (NWO)"
 3. Fill in and submit the form (see the instructions below)
 
-#### Instructions to fill in the EINFRA grant form
+### Instructions to fill in the EINFRA grant form
 
 Most fields in the form are self explanatory or optional. Here we explain the fields that aren't self explanatory:
 
-*Description*
+#### Description
 
 Put here a small description of what you intent to do. Explain that you want to do a data donation study.
 
-*Scientific project descrition*
+#### Scientific project description
 
 Put down the description of your research project, you could copy and paste this from a grant proposal.
 
-*Technical project requirements*
+#### Technical project requirements
 
 In this section you need to explain what resources you need. Based on the resources you need you will receive the appropriate amount of credits.
 This is an example descrition of the technical project requirements for data donation:
@@ -58,33 +58,32 @@ This is an example descrition of the technical project requirements for data don
 
 You need to adapt it to your situation. You should realize that if the workspace is provisioned (meaning its "on" or "running") credits will be deducted. Try to be realistic for the amounts of weeks you need, but take into account unforseen events.
 
-*Resources*
+#### Resources
 
 Research Cloud - HPC Cloud
 
-*Research Drive: Do you need storage in Research Drive?*
+#### Research Drive: Do you need storage in Research Drive?
 
 50 GiB
 
-#### After you received the EINFRA grant
+### After you received the EINFRA grant
 
 You need to contact [datadonation.eu](https://datadonation.eu/) they will make the "Next self service" catalog item available to you.
 
 
-### Self service Next (community version)
+## Self service Next (community version)
 
 Next is a free and open source tool and you could host it yourself. You can find Next [here](https://github.com/eyra/mono/blob/master/SELFHOSTING.md). You can try it out using Docker, check the tutorial {doc}`./next-in-docker`
 
 
-
-### Which option should I choose?
+## Which option should I choose?
 
 * Next as a paid service: If you have research budget; want to be unburdened and get your data donation study done, this is the best option.
 * Self service community Next on Surf Research Cloud: You are a researcher at a Dutch university with no budget this is the best option. When choosing this option you have to realize that it comes with no service or warranties, you have to know what you are doing.
 * Self service community Next: If you want to provide Next as a service to your organization.
 
 
-### Add data donation task to your data donation study on Next
+## Add data donation task to your data donation study on Next
 
 After you have created your data donation task with this repository, you can use this task directly in Next. You can do this as follows:
 

doc/source/articles/index.rst → doc/source/getting_started/index.rst

@@ -1,13 +1,13 @@
-Articles
-========
+Getting Started
+===============
 
 .. toctree::
    :maxdepth: 2
 
-   introduction-to-data-donation.md
    installation.md
    creating-your-own-data-donation-task.md
    visualizations.md
-   data-donation-checklist.md
+   next-and-port.rst
    deployment.md
    next-in-docker.md
+   data-donation-checklist.md

doc/source/getting_started/next-and-port.rst

@@ -0,0 +1,42 @@
+=============
+Next and Port
+=============
+
+
+This diagram indicates the relations between Next, Port and the Data Donation task
+
+.. figure:: /_static/arch.png
+   :alt: Alternative text
+   :align: center
+
+   The relationship between the Data Donation Task and Next
+
+
+Next
+====
+
+The data donation task is primarily created to be used in conjunction with [Next](https://github.com/eyra/mono). Next is a software as a service platform developed by [Eyra](https://eyra.co/) to facilitate scientific research.
+
+Port
+====
+
+Port is a service on Next which you can use to perform a complete data donation study. You can use Port to:
+
+- Personalize your study
+- Setup data storage for your study
+- Setup the study itself
+- Integrate with qualtrics
+- Administer the data donation task to participants
+- Track the progress of your study
+
+The Data Donation Task
+======================
+
+The data donation task is a fork of [Feldspar](https://github.com/eyra/feldspar) with some extra functionalities added to it. Feldspar is a framework which can be used to build applications specifically for Next. An example of such an application is the data donation task which you can find in this repository. 
+
+
+Frontend
+========
+
+The data donation task (and Feldspar) is only a *front end* to be used with Next. In order for it to be used in a live study it needs to be hosted with Next.
+The wiki will discuss the options you have for using the data donation task in an actual study.

doc/source/articles/next-in-docker.md → doc/source/getting_started/next-in-docker.md

@@ -31,12 +31,12 @@ We are going to create a folder with the following structure:
 ```
 .
 ├── docker-compose.yaml
-├── proxy
-│   ├── certs
-│   │   ├── nginx-selfsigned.crt
-│   │   └── nginx-selfsigned.key
-│   └── conf
-│       └── nginx.conf
+└── proxy
+    ├── certs
+    │   ├── nginx-selfsigned.crt
+    │   └── nginx-selfsigned.key
+    └── conf
+        └── nginx.conf
 ```
 
 In the next step we are going to create the files.