Merge pull request #141 from marcobarilari/marco_sphinx-docs

Sphynx doc pt.2 (fix warnings)

Author: marcobarilari

docs/source/function_description.rst

@@ -1,5 +1,5 @@
 Function description
-====================
+********************
 
 The functions of our pipeline
 
@@ -21,20 +21,27 @@ List of functions in the ``src`` folder.
 
 ----
 
+Aperture
+========
+
 List of functions in the ``src/aperture`` folder.
 
+(to add saveAperture)
+
 .. module:: src.aperture
 
 .. autofunction:: apertureTexture
 .. autofunction:: eccenLogSpeed
 .. autofunction:: getApertureName
-.. autofunction:: saveAperture
 .. autofunction:: saveApertures
 .. autofunction:: smoothOval
 .. autofunction:: smoothRect
 
 ----
 
+Dot
+===
+
 List of functions in the ``src/dot`` folder.
 
 .. module:: src.dot
@@ -53,6 +60,9 @@ List of functions in the ``src/dot`` folder.
 
 ----
 
+Errors
+======
+
 List of functions in the ``src/errors`` folder.
 
 .. module:: src.errors
@@ -64,6 +74,9 @@ List of functions in the ``src/errors`` folder.
 
 ----
 
+Fixation
+========
+
 List of functions in the ``src/fixation`` folder.
 
 .. module:: src.fixation
@@ -73,6 +86,9 @@ List of functions in the ``src/fixation`` folder.
 
 ----
 
+Keyboard
+========
+
 List of functions in the ``src/keyboard`` folder.
 
 .. module:: src.keyboard
@@ -86,6 +102,9 @@ List of functions in the ``src/keyboard`` folder.
 
 ----
 
+Randomization
+=============
+
 List of functions in the ``src/randomization`` folder.
 
 .. module:: src.randomization
@@ -96,6 +115,9 @@ List of functions in the ``src/randomization`` folder.
 
 ----
 
+Screen
+======
+
 List of functions in the ``src/screen`` folder.
 
 .. module:: src.screen
@@ -105,6 +127,9 @@ List of functions in the ``src/screen`` folder.
 
 ----
 
+Utilities
+=========
+
 List of functions in the ``src/utils`` folder.
 
 (to add makeGif)

src/dot/initDots.m

@@ -20,8 +20,7 @@
     % dots.isSignal : signal dots (1) and those are noise dots (0)
     % dots.directionAllDots
     % dots.lifeTime : in frames
-    % dots.speeds : [ndots, 2] ; horizontal and vertical speed ; in pixels per
-    %   frame
+    % dots.speeds : [ndots, 2] ; horizontal and vertical speed ; in pixels per frame
     % dots.speedPixPerFrame
 
     dots.direction = thisEvent.direction(1);

src/eyeTracker.m

@@ -1,29 +1,37 @@
 % (C) Copyright 2020 CPP_PTB developers
 
 function [el, cfg] = eyeTracker(input, cfg, varargin)
-    % [el] = eyeTracker(input, cfg, varargin)
     %
     % Wrapper function that deals with all the necessery actions to implement
-    %  Eye Tracker recording with eyelink.
+    % Eye Tracker recording with eyelink.
     %
-    % INPUT
+    % USAGE:
     %
-    % - action: Defines what we want the function to do
-    %  - Calibration: to initialize EyeLink and run calibration
-    %    -- 'default calibration' (default) will run a calibration with 6 points
-    %    -- 'custom calibration'  (cfg.eyeTracker.defaultCalibration = 'false') will run a
-    %        calibration with 6 points but the experimenter can choose their position on the screen
-    %  - StartRecording: to start eye movements recording
-    %  - Message: will add a tag (e.g. 'Block_n1') in the ET output file, the tag is a string and it
-    %        is input from `varargin`
-    %  - StopRecordings: to stop eye movements recornding
-    %  - Shutdown: to save the `.edf` file with BIDS compliant name, from cpp-lln-lab/CPP_BIDS, in
-    %    the output folder and shut the connection between the stimulation computer and the EyeLink
-    %    computer
+    %   function [el, cfg] = eyeTracker(input, cfg, [message])
     %
-    %  OUTPUT
+    % :param input: Defines what we want the function to do
+    % :type input: string
+    % :param cfg: structure that stores any info regarding the experiment
+    % :type cfg: struct
+    % :param message: optional argument to pass in when you want to tag the output in a specific
+    %                 moment of the experiment (for example ``Experiment-start``)
+    % :type message: string
     %
-    % `el` is a structure where are stored EyeLink setup variables
+    % :returns: - :el: (struct) stores info related to the Eye Tracker
+    %           - :cfg: (struct)
+    %
+    % - ``Calibration`` to initialize EyeLink and run calibration
+    % - ``default calibration`` (default) will run a calibration with 6 points
+    % - ``custom calibration`` (``cfg.eyeTracker.defaultCalibration = 'false'``) will run
+    %   a calibration with 6 points but the experimenter can choose their position
+    %   on the screen
+    % - ``StartRecording``: to start eye movements recording
+    % - ``Message``: will add a tag (e.g. ``Block_n1``) in the ET output file, the tag is a
+    %   string and it is input from `varargin`
+    % - ``StopRecordings``: to stop eye movements recording
+    % - ``Shutdown``: to save the ``.edf`` file with BIDS compliant name, from
+    %   cpp-lln-lab/CPP_BIDS, in the output folder and shut the connection between the
+    %   stimulation computer and the EyeLink computer
 
     if ~cfg.eyeTracker.do
 

src/keyboard/checkAbort.m

@@ -1,25 +1,37 @@
 % (C) Copyright 2020 CPP_PTB developers
 
 function checkAbort(cfg, deviceNumber)
-    % checkAbort(cfg, deviceNumber)
     %
-    % Check for experiment abortion from operator
-    % When no deviceNumber is set then it will check the default device
-    % When an abort key s detected this will set a global variable and throw a
+    % Check for experiment abortion from operator. When no deviceNumber is set then it will check
+    % the default device. When an abort key is detected this will set a global variable and throw a
     % specific error that can then be catched.
     %
-    % Maint script
-    % try
-    %     % Your awesome experiment
-    % catch ME % when something goes wrong
-    %     switch ME.identifier
+    % USAGE::
+    %
+    %   checkAbort(cfg, deviceNumber)
+    %
+    % Examples::
+    %
+    %   try
+    %
+    %   % Your awesome experiment
+    %
+    %   catch ME % when something goes wrong
+    %
+    %       switch ME.identifier
+    %
     %         case 'checkAbort:abortRequested'
-    %             % stuff to do when an abort is requested (save data...)
+    %
+    %         % stuff to do when an abort is requested (save data...)
+    %
     %         otherwise
-    %             % stuff to do otherwise
-    %             rethrow(ME) % display the error
-    %     end
-    % end
+    %
+    %          % stuff to do otherwise
+    %          rethrow(ME) % display the error
+    %
+    %       end
+    %   end
+    %
 
     if nargin < 1 || isempty(cfg)
         error('I need at least one input.');

src/keyboard/getResponse.m

@@ -1,60 +1,68 @@
 % (C) Copyright 2020 CPP_PTB developers
 
 function responseEvents = getResponse(action, deviceNumber, cfg, getOnlyPress)
-    % responseEvents = getResponse(action, deviceNumber, cfg, getOnlyPress)
     %
-    % Wrapper function to use KbQueue
+    % Wrapper function to use KbQueue. The queue will be listening to key presses
+    % on a keyboard device:
+    % ``cfg.keyboard.responseBox`` or ``cfg.keyboard.keyboard`` are 2 main examples.
+    % When no ``deviceNumber`` is set then it will listen to the default device.
+    % Check the ``CPP_getResponseDemo`` for a quick script on how to use it.
     %
-    % The queue will be listening to key presses on a keyboard device:
-    % cfg.keyboard.responseBox or cfg.keyboard.keyboard are 2 main examples.
+    % USAGE::
     %
-    % When no deviceNumber is set then it will listen to the default device.
+    %   responseEvents = getResponse(action, deviceNumber, cfg, getOnlyPress)
     %
-    % Check the CPP_getResponseDemo for a quick script on how to use it.
+    % :param action: Defines what we want the function to do
+    % :param deviceNumber: device number of the keyboard or trigger box in MRI
+    % :type deviceNumber: integer
+    % :param cfg:
+    % :param getOnlyPress: if set to true the function will only return the key presses and will not
+    %                      return when the keys were released (default=true). See the section on
+    %                      `Returns` below for more info
     %
+    % :returns:
     %
-    % INPUT
+    % - :responseEvents: returns all the keypresses and return them
+    %                    as a structure with field names that make it easier
+    %                    to save the output of in a BIDS format
     %
-    % - action: Defines what we want the function to do
-    %  - init: to initialise the queue
-    %  - start: to start listening to keypresses
-    %  - check: checks all the key presses events since 'start', or since last
-    %    'check' or 'flush' (whichever was the most recent)
-    %    -- can check for demand to abort if the escapeKey is listed in the
-    %       Keys of interest.
-    %    -- can only check for demands to abort when getResponse('check') is called:
-    %       so there will be a delay between the key press and the experiment stopping
-    %    -- abort errors send specific signals that allow the catch to get
-    %       them and allows us to "close" nicely
-    %  - flush: empties the queue of events in case you want to restart from a clean
-    %    queue
-    %  - stop: stops listening to key presses
+    %   - ``responseEvents.onset`` this is an absolute value and you should substract
+    %     the "experiment start time" to get a value relative to when the experiment was started.
     %
-    % - getOnlyPress: if set to true the function will only return the key presses and
-    %    will not return when the keys were released (default=true)
-    %    See the section on OUTPUT below for more info
+    %   - ``responseEvents.trial_type = response``
     %
+    %   - ``responseEvents.duration = 0``
     %
+    %   - ``responseEvents.keyName`` the name of the key pressed
     %
-    % OUTPUT
+    %   - ``responseEvents(iEvent,1).pressed`` if
     %
-    % responseEvents: returns all the keypresses and return them as a structure
-    % with field names that make it easier to save the output of in a BIDS
-    % format
+    %      - ``pressed == 1``  --> the key was pressed
+    %      - ``pressed == 0``  --> the key was released
     %
-    % responseEvents.onset : this is an absolute value and you should
-    %   substract the "experiment start time" to get a value relative to when the
-    %   experiment was started.
+    % ---
     %
-    % responseEvents.trial_type = 'response';
+    % ``action`` options:
     %
-    % responseEvents.duration = 0;
+    % - ``init`` to initialise the queue
     %
-    % responseEvents.keyName : the name of the key pressed
+    % - ``start`` to start listening to keypresses
+    %
+    % - ``check`` checks all the key presses events since 'start', or since last 'check'
+    %   or 'flush' (whichever was the most recent)
+    %
+    %   - can check for demand to abort if the ``escapeKey`` is listed in the Keys of interest
+    %
+    %   - can only check for demands to abort when ``getResponse('check')`` is called
+    %     so there will be a delay between the key press and the experiment stopping
+    %
+    %   - abort errors send specific signals that allow the catch to get them and allows us
+    %     to "close" nicely
+    %
+    % - ``flush`` empties the queue of events in case you want to restart from a clean queue
+    %
+    % - ``stop`` stops listening to key presses
     %
-    % responseEvents(iEvent,1).pressed : if
-    %   pressed == 1  --> the key was pressed
-    %   pressed == 0  --> the key was released
 
     if nargin < 2 || isempty(deviceNumber)
         deviceNumber = -1;

src/readAndFilterLogfile.m

@@ -1,27 +1,30 @@
 % (C) Copyright 2020 CPP_PTB developers
 
-function outputFiltered = readAndFilterLogfile(columnName, filterBy, varargin)
-    % outputFiltered = readOutputFilter(filterHeader, filterContent, varargin)
+function [outputFiltered] = readAndFilterLogfile(columnName, filterBy, varargin)
     %
-    % It will display in the command window the content of the `output.tsv' filtered by one element
-    % of a target column.
+    % It will display in the command window the content of the `output.tsv` filtered
+    % by one element of a target column. Dependecies: bids_matlab (from CPP_BIDS)
     %
-    % DEPENDENCIES:
-    %  - bids_matlab (from CPP_BIDS)
+    % USAGE:
     %
-    % INPUT:
+    %   [outputFiltered] = readOutputFilter(filterHeader, filterContent, varargin)
     %
-    %  - columnName: string, the header of the column where the content of insterest is stored
-    %    (e.g., for 'trigger' will be 'trial type')
-    %  - filterBy: string, the content of the column you want to filter out. It can take just
-    %    part of the content name (e.g., you want to display the triggers and you have
-    %    'trigger_motion' and 'trigger_static', 'trigger' as input will do)
-    %  - varargin: either cfg (to display the last run output) or the file path as string
+    % :param columnName: the header of the column where the content of insterest is stored
+    %                    (e.g., for 'trigger' will be 'trial type')
+    % :type columnName: string
+    % :param filterBy: the content of the column you want to filter out. It can take just
+    %                  part of the content name (for example, you want to display the triggers and
+    %                  you have ``trigger_motion`` and ``trigger_static``, ``trigger`` as input
+    %                  will do)
+    % :type filterBy: string
+    % :param varargin: either ``cfg`` (to display the last run output) or the file path as string
+    %
+    % :returns:
+    %
+    % - :outputFiltered: dataset with only the specified content to see it in the
+    %                    command window use display(outputFiltered)
     %
-    % OUTPUT:
     %
-    %  - outputFiltered: dataset with only the specified content, to see it in the command window
-    %    use display(outputFiltered)
 
     % Checke if input is cfg or the file path
     if ischar(varargin{1})

src/templates/templateFunction.m

@@ -0,0 +1,29 @@
+% (C) Copyright 2020 CPP_PTB developers
+
+function [argout1, argout2] = templateFunction(argin1, argin2, argin3)
+    %
+    % Short description of what the function does goes here.
+    %
+    % USAGE::
+    %
+    %   [argout1, argout2] = templateFunction(argin1, [argin2 == default,] [argin3])
+    %
+    % :param argin1: (dimension) obligatory argument. Lorem ipsum dolor sit amet,
+    %                consectetur adipiscing elit. Ut congue nec est ac lacinia.
+    % :type argin1: type
+    % :param argin2: optional argument and its default value. And some of the
+    %               options can be shown in litteral like ``this`` or ``that``.
+    % :type argin2: string
+    % :param argin3: (dimension) optional argument
+    %
+    % :returns: - :argout1: (type) (dimension)
+    %           - :argout2: (type) (dimension)
+    %
+    % .. todo:
+    %
+    %    - item 1
+    %    - item 2
+
+    % The code goes below
+
+end