Merge pull request #92 from Remi-Gau/remi-doc

update DOC and add tests

Author: Remi-Gau

README.md

@@ -1,5 +1,5 @@
 [![](https://img.shields.io/badge/Octave-CI-blue?logo=Octave&logoColor=white)](https://github.com/cpp-lln-lab/CPP_PTB/actions)
-![](https://github.com/cpp-lln-lab/CPP_PTB/workflows/CI/badge.svg) 
+![](https://github.com/cpp-lln-lab/CPP_PTB/workflows/CI/badge.svg)
 
 [![Build Status](https://travis-ci.com/cpp-lln-lab/CPP_PTB.svg?branch=master)](https://travis-ci.com/cpp-lln-lab/CPP_PTB)
 
@@ -11,33 +11,30 @@
 
 # CPP_PTB
 
-<!-- vscode-markdown-toc -->
-* 1. [Requirements](#Requirements)
-* 2. [Code guidestyle](#Codeguidestyle)
-* 3. [How to install](#Howtoinstall)
-	* 3.1. [Download with git](#Downloadwithgit)
-	* 3.2. [Add as a submodule](#Addasasubmodule)
-		* 3.2.1. [Example for submodule usage](#Exampleforsubmoduleusage)
-	* 3.3. [Direct download](#Directdownload)
-* 4. [Setting up keyboards](#Settingupkeyboards)
-* 5. [Structure](#Structure)
-* 6. [Annexes](#Annexes)
-	* 6.1. [Experiment template [ WIP ]](#ExperimenttemplateWIP)
-	* 6.2. [devSandbox (stand-alone)](#devSandboxstand-alone)
-* 7. [Contributors ✨](#Contributors)
-
-<!-- vscode-markdown-toc-config
-	numbering=true
-	autoSave=true
-	/vscode-markdown-toc-config -->
-<!-- /vscode-markdown-toc -->
+<!-- TOC -->
+
+- [CPP_PTB](#cpp_ptb)
+	- [Requirements](#requirements)
+	- [Documentation](#documentation)
+	- [Content](#content)
+	- [How to install](#how-to-install)
+		- [Download with git](#download-with-git)
+		- [Add as a submodule](#add-as-a-submodule)
+			- [Example for submodule usage](#example-for-submodule-usage)
+		- [Direct download](#direct-download)
+		- [Add CPP_PTB globally to the matlab path](#add-cpp_ptb-globally-to-the-matlab-path)
+	- [Code style guide](#code-style-guide)
+	- [Unit tests](#unit-tests)
+	- [Contributors ✨](#contributors-)
+
+<!-- /TOC -->
 
 
 This is the Crossmodal Perception and Plasticity lab (CPP) PsychToolBox (PTB) toolbox.
 
-Those functions are mostly wrappers around some PTB functions to facilitate their use and to have a codebase to facilitate their reuse.
+Those functions are mostly wrappers around some PTB functions to facilitate their use and their reuse (#DontRepeatYourself)
 
-##  1. <a name='Requirements'></a>Requirements
+## Requirements
 
 Make sure that the following toolboxes are installed and added to the matlab / octave path.
 
@@ -47,58 +44,65 @@ For instructions see the following links:
 |----------------------------------------------------------|--------------|
 | [PsychToolBox](http://psychtoolbox.org/)                 | >=3.0.14     |
 | [Matlab](https://www.mathworks.com/products/matlab.html) | >=2015b      |
-| or [octave](https://www.gnu.org/software/octave/)        | 4.?          |
+| or [Octave](https://www.gnu.org/software/octave/)        | 4.?          |
 
-The exact version required for this to work but it is known to work with:
+Tested:
 -   matlab 2015b or octave 4.2.2 and PTB 3.0.14.
 
-##  2. <a name='Codeguidestyle'></a>Code guidestyle
+## Documentation
 
-We use the `camelCase` to more easily differentiates our functions from the ones from PTB that use a `PascalCase`.
-We use the following regular expression for function names: `[a-z]+(([A-Z]|[0-9]){1}[a-z]+)*`.
+All the documentation is accessible [here](./docs/00_index.md).
 
-We keep the McCabe complexity as reported by the [check_my_code function](https://github.com/Remi-Gau/check_my_code) below 15.
+## Content
 
-We use the [MISS_HIT linter](https://florianschanda.github.io/miss_hit/style_checker.html) to automatically fix some linting issues. The code style and quality is also checked during the continuous integration.
+```bash
+├── demos # quick demo of how to use some functions
+├── dev # templates for experiment (will be moved out soon)
+├── docs # documentation
+├── manualTests # all the tests that cannot be automated (yet)
+├── src # actual code of the CPP_PTB
+│   ├── aperture # function related to create apertur (circle, wedge, bar...)
+│   ├── dot # functions to simplify the creations of RDK
+│   ├── errors # all error functions
+│   ├── fixation # to create fixation cross, dots
+│   ├── keyboard # to collect responses, abort experiment...
+│   ├── randomization # functions to help with trial randomization
+│   └── utils # set of general functions
+└── tests # all the tests that that can be run by github actions
+```
 
-##  3. <a name='Howtoinstall'></a>How to install
+## How to install
 
-###  3.1. <a name='Downloadwithgit'></a>Download with git
+### Download with git
 
 ``` bash
 cd fullpath_to_directory_where_to_install
 # use git to download the code
 git clone https://github.com/cpp-lln-lab/CPP_PTB.git
 # move into the folder you have just created
 cd CPP_PTB
-# add the src folder to the matlab path and save the path
-matlab -nojvm -nosplash -r "addpath(fullfile(pwd)); savepath ();"
 ```
 
-Then get the latest commit:
+Then get the latest commit to stay up to date:
 ```bash
 # from the directory where you downloaded the code
 git pull origin master
 ```
 
 To work with a specific version, create a branch at a specific version tag number
 ```bash
-# creating and checking out a branch that will be calle version1 at the version tag v0.0.1
-git checkout -b version1 v0.0.1
+# creating and checking out a branch that will be called version1 at the version tag v1.0.0
+git checkout -b version1 v1.0.0
 ```
 
-###  3.2. <a name='Addasasubmodule'></a>Add as a submodule
+### Add as a submodule
 
 Add it as a submodule in the repo you are working on.
 
 ``` bash
 cd fullpath_to_directory_where_to_install
 # use git to download the code
 git submodule add https://github.com/cpp-lln-lab/CPP_PTB.git
-# move into the folder you have just created
-cd CPP_PTB
-# add the src folder to the matlab path and save the path
-matlab -nojvm -nosplash -r "addpath(fullfile(pwd))"
 ```
 
 To get the latest commit you then need to update the submodule with the information
@@ -109,7 +113,7 @@ git submodule update --remote --merge
 
 Remember that updates to submodules need to be committed as well.
 
-####  3.2.1. <a name='Exampleforsubmoduleusage'></a>Example for submodule usage
+#### Example for submodule usage
 
 So say you want to clone a repo that has some nested submodules, then you would type this to get the content of all the submodules at once (here with my experiment repo):
 ``` bash
@@ -133,7 +137,7 @@ git submodule foreach --recursive 'git submodule init'
 git submodule foreach --recursive 'git submodule update'
 ```
 
-###  3.3. <a name='Directdownload'></a>Direct download
+### Direct download
 
 Download the code. Unzip. And add to the matlab path.
 
@@ -145,112 +149,41 @@ Or take the latest commit (NOT RECOMMENDED):
 
 https://github.com/cpp-lln-lab/CPP_PTB/archive/master.zip
 
-##  4. <a name='Settingupkeyboards'></a>Setting up keyboards
-
-To select a specific keyboard to be used by the experimenter or the participant, you need to know
-the value assigned by PTB to each keyboard device.
+### Add CPP_PTB globally to the matlab path
 
-To know this copy-paste this on the command window:
+This is NOT RECOMMENDED as this might create conflicts if you use different versions of CPP_PTB as sub-modules.
 
-``` matlab
-[keyboardNumbers, keyboardNames] = GetKeyboardIndices;
+Also note that this might not work at all if you have not set a command line alias to start Matlab from a terminal window by just typing `matlab`. :wink:
 
-disp(keyboardNumbers);
-disp(keyboardNames);
+```bash
+# from within the CPP_PTB folder
+matlab -nojvm -nosplash -r "addpath(genpath(fullfile(pwd, 'src'))); savepath(); path(); exit();"
 ```
 
-You can then assign a specific device number to the main keyboard or the response box in the `cfg` structure
-
--   `cfg.keyboard.responseBox` would be the device number of the device used by the participant to give his/her
-response: like the button box in the scanner or a separate keyboard for a behavioral experiment
--   `cfg.keyboard.keyboard` would be the device number of the keyboard on which the experimenter will type or
-press the keys necessary to start or abort the experiment.
-
-`cfg.keyboard.responseBox` and `cfg.keyboard.keyboard` can be different or the same.
-
-Using empty vectors (ie `[]`) or a negative value for those means that you will let PTB find and use the default device.
-
-##  5. <a name='Structure'></a>Structure
-
-The `cfg` structure is where most of the information about your experiment will be defined.
-
-Below we try to outline what it contains.
-
-```matlab
-
-cfg.testingDevice = 'pc';
-
-% cfg.color
-cfg.keyboard.keyboard = [];
-cfg.keyboard.responseBox = [];
-cfg.keyboard.responseKey = {};
-cfg.keyboard.escapeKey = 'ESCAPE';
-
-% cfg.debug
-cfg.debug.do = true;
-cfg.debug.transpWin = true;
-cfg.debug.smallWin = true;
-
-% cfg.text
-cfg.text.font
-cfg.text.size
-cfg.text.style
-
-% cfg.color
-cfg.color.background
-
-% cfg.screen
-cfg.screen.monitorWidth
-cfg.screen.monitorDistance
-cfg.screen.idx
-cfg.screen.win
-cfg.screen.winRect
-cfg.screen.winWidth
-cfg.screen.winHeight
-cfg.screen.center
-cfg.screen.FOV
-cfg.screen.ppd
-cfg.screen.ifi
-cfg.screen.monRefresh
-
-% cfg.audio
-cfg.audio.do
-cfg.audio.pahandle
-cfg.audio.devIdx
-cfg.audio.playbackMode
-cfg.audio.requestedLatency
-cfg.audio.fs
-cfg.audio.channels
-cfg.audio.initVolume
-cfg.audio.pushSize  
-cfg.audio.requestOffsetTime
-cfg.audio.reqsSampleOffset
-
-% cfg.mri
-cfg.mri.repetitionTime
-cfg.mri.triggerNb
-cfg.mri.triggerKey
-```
+## Code style guide
+
+We use the `camelCase` to more easily differentiates our functions from the ones from PTB that use a `PascalCase`.
 
-##  6. <a name='Annexes'></a>Annexes
+In practice, we use the following regular expression for function names: `[a-z]+(([A-Z]|[0-9]){1}[a-z]+)*`.
 
-###  6.1. <a name='ExperimenttemplateWIP'></a>Experiment template [ WIP ]
+> Regular expressions look scary but are SUPER useful to sort through filenames:
+> - A quick [intro to regular expression](https://www.rexegg.com/)
+> - And many websites allow you to "design and test" your regular expression:
+>   - [regexr](https://regexr.com/)
+>   - [regexper](https://regexper.com/#%5Ba-z%5D%2B%28%28%5BA-Z%5D%7C%5B0-9%5D%29%7B1%7D%5Ba-z%5D%2B%29)
+>   - ...
 
-###  6.2. <a name='devSandboxstand-alone'></a>devSandbox (stand-alone)
+We keep the McCabe complexity below 15 as reported by the [check_my_code function](https://github.com/Remi-Gau/check_my_code) or the [MISS_HIT code checker](https://florianschanda.github.io/miss_hit). A couple of code quality metrics are also checked automatically by MISS_HIT (avoiding functions with too many nested `if` blocks).
 
-This script is a stand-alone function that can be useful as a sandbox to develop the PTB audio/visual stimulation of your experiment. No input/output required.
+We use the [MISS_HIT linter](https://florianschanda.github.io/miss_hit/style_checker.html) to automatically fix some linting issues.
 
-Here, a tutorial from https://peterscarfe.com/contrastgratingdemo.html is provided for illustrative purpose (notice that some variable names are updated to our code style). For your use, you will delete that part.
+The code style and quality is also checked during the [continuous integration](./.travis.yml).
 
-It is composed of two parts:
- - a fixed structure that will initialize and close PTB in 'debug mode'
-    (`PsychDebugWindowConfiguration`, `SkipSyncTests`)
- - the actual sandbox where to set your dynamic variables (the stimulation
-   parameters) and the 'playground' where to develop the stimulation code
+## Unit tests
 
- When you are happy with it, ideally you will move the vars in `setParameters.m` and the stimulation code in a separate function in `my-experiment-folder/subfun`. The code style and variable names are the same used in `cpp-lln-lab/CPP_PTB` github repo, therefore it should be easy to move everything in your experiment scripts (see the template that is annexed in `cpp-lln-lab/CPP_PTB`).
+Unit tests are run with the mox unit toolbox and automated with github action on Octave.
 
-##  7. <a name='Contributors'></a>Contributors ✨
+## Contributors ✨
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):