Merge pull request #163 from Remi-Gau/remi-update_doc

[DOC] update doc and jupyter notebook

.readthedocs.yml

@@ -23,4 +23,4 @@ formats:
 python:
   version: 3.7
   install:
-    - requirements: docs/requirements.txt
+    - requirements: requirements.txt

docs/installation.md

@@ -14,19 +14,22 @@
 
 <!-- lint enable -->
 
+## Use the CPP templates for PsychToolBox experiments
+
+The easiest way to use this repository is to create a new repository by using
+the
+[template PTB experiment repository](https://github.com/cpp-lln-lab/template_PTB_experiment):
+this creates a new repository on your github account with all the basic folders,
+files and submodules (including CPP_BIDS) already set up. You only have to then
+clone the repository and you are good to go.
+
 ## 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_BIDS.git
-
-# move into the folder you have just created
-cd CPP_BIDS
-
-# add the src folder to the matlab path and save the path
-matlab -nojvm -nosplash -r "addpath(fullfile(pwd, 'src')); savepath ();"
+# use git to download the code and the submodules
+git clone --recurse-submodules https://github.com/cpp-lln-lab/CPP_BIDS.git
 ```
 
 Then get the latest commit:
@@ -53,12 +56,6 @@ cd fullpath_to_directory_where_to_install
 
 # use git to download the code
 git submodule add https://github.com/cpp-lln-lab/CPP_BIDS.git
-
-# move into the folder you have just created
-cd CPP_BIDS
-
-# add the src folder to the matlab path and save the path
-matlab -nojvm -nosplash -r "addpath(fullfile(pwd, 'src'))"
 ```
 
 To get the latest commit you then need to update the submodule with the
@@ -83,7 +80,7 @@ git clone https://github.com/user_name/myExperiment.git
 # go into the directory
 cd myExperiment
 
-# initialize and get the content of the first level of submodules  (e.g. CPP_PTB and CPP_BIDS)
+# initialize and get the content of the first level of submodules
 git submodule init
 git submodule update
 
@@ -94,6 +91,8 @@ git submodule foreach --recursive 'git submodule update'
 
 ## Direct download
 
+NOT RECOMMENDED.
+
 Download the code. Unzip. And add to the matlab path.
 
 Pick a specific version from

docs/source/function_description.rst

@@ -12,6 +12,21 @@ List of functions in the ``src`` folder.
 .. autofunction:: createDatasetDescription
 .. autofunction:: createFilename
 .. autofunction:: createJson
+
+``createJson`` can be used to save in a
+human readable format the extra parameters that you used to run your experiment. 
+This will most likely make the json file non-bids compliant but it can prove useful,
+to keep this information in your source dataset
+for when you write your methods sections 2 years later after running the experiment.
+This ensures that those are the exact parameters you used and you won't have 
+to read them from the ``setParameters.m`` file and wonder 
+if those might have been modified when running the experiment 
+and you did not commit and tagged that change with git.
+
+And for the love of the flying spaghetti monster do not save all your
+parameters in a `.mat` file: think of the case when you won't have Matlab or
+Octave installed on a computer (plus not everyone uses those).
+
 .. autofunction:: readAndFilterLogfile
 .. autofunction:: saveEventsFile
 .. autofunction:: userInputs

docs/source/utilities.rst

@@ -8,10 +8,12 @@ List of functions in the ``utils`` folder.
 .. automodule:: src.utils
 
 .. autofunction:: checkCppBidsDependencies
+.. autofunction:: checkInput
 .. autofunction:: createValidName
 .. autofunction:: getFullFilename
 .. autofunction:: initializeExtraColumns
 .. autofunction:: isPositiveInteger
+.. autofunction:: nanPadding
 .. autofunction:: printCreditsCppBids
 .. autofunction:: removeAllDateSuffix
 .. autofunction:: removeDateSuffix