diff --git a/.gitignore b/.gitignore index a0a48066..e97e782b 100644 --- a/.gitignore +++ b/.gitignore @@ -6,4 +6,10 @@ # exclude content of logfiles folders *.tsv *.mat -check_my_code_report.txt \ No newline at end of file +check_my_code_report.txt + +# exclude content of files for virtual env (mostly for the doc) +cpp_ptb + +# ignore file created by sphynx +/docs/build diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 00000000..6f095f08 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,26 @@ +# .readthedocs.yml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/source/conf.py + builder: html + fail_on_warning: true + +# Build documentation with MkDocs +#mkdocs: +# configuration: mkdocs.yml + +# Optionally build your docs in additional formats such as PDF +formats: + - pdf + +# Optionally set the version of Python and requirements required to build your docs +python: + version: 3.7 + install: + - requirements: docs/requirements.txt \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..7724da53 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,139 @@ +# Setting up sphinx to create a matlab doc + +## Set up virtual environment + +```bash +virtualenv -p python3 cpp_ptb +source cpp_ptb/bin/activate + +pip install -r requirements.txt +``` + +## Quick start on the doc + +See the [sphinx doc](https://www.sphinx-doc.org/en/master/usage/quickstart.html) +for more. + +This +[blog post](https://medium.com/@richdayandnight/a-simple-tutorial-on-how-to-document-your-python-project-using-sphinx-and-rinohtype-177c22a15b5b) +is also useful. + +```bash +cd docs +sphinx-quickstart # launch a basic interactive set up of sphinx +``` + +Answer the questions on prompt. + +## Setting up conf.py for matlab doc + +Following the documentation from +[matlabdomain for sphinx](https://github.com/sphinx-contrib/matlabdomain). + +Specify the extensions you are using: + +```python +extensions = [ + 'sphinxcontrib.matlab', + 'sphinx.ext.autodoc'] +``` + +`matlab_src_dir` in `docs/source/conf.py` should have the path (relative to `conf.py`) +to the folder containing your matlab code: + +```python +matlab_src_dir = os.path.dirname(os.path.abspath('../../src')) +``` + +## reStructured text markup + +reStructured text mark up +[primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). + +## "Templates" + +There are different ways you can document the help section of your matlab +functions so it can be documented automatically by sphinx. + +```matlab +function y = my_function(arg1, arg2) + % + % Describe what the function does here. + % + % y = my_function_napoleon(arg1, arg2) + % + % :param arg1: The first input value + % :param arg2: The second input value + % :returns: The input value multiplied by two + + y = arg1 + arg2 +``` + +"Napoleon" way more similar to Numpy: + +```matlab +function y = my_function_napoleon(arg1, arg2) + % + % Describe what the function does here. + % + % y = my_function_napoleon(arg1, arg2) + % + % Parameters: + % x: The first input value + % + % y: The second input value + % + % Returns: + % The input value multiplied by two + + y = x * 2; +``` + +You then just need to insert this in your `.rst` file for the documentation to +be done automatically. + +```rst + +.. automodule:: src .. <-- This is necessary for autodocumenting the rest + +.. autofunction:: my_function + +.. autofunction:: my_function_napoleon +``` + +## Build the documentation locally + +From the `docs` directory: + +```bash +sphinx-build -b html source build +``` + +This will build an html version of the doc in the `build` folder. + +## Buid the documentation with Read the Docs + +Add a [`.readthedocs.yml`](../.readthedocs.yml) file in the root of your repo. + +See [HERE](https://docs.readthedocs.io/en/stable/config-file/v2.html) for +details. + +You can then trigger the build of the doc by going to the [read the docs](https://readthedocs.org) +website. + +You might need to be added as a maintainer of the doc. + +The doc can be built from any branch of a repo. + + + +## Other matlab projects that use + +### Sphinx + +Some are listed +[sphinx-contrib/matlabdomain#users](https://github.com/sphinx-contrib/matlabdomain#users) + +### Read the docs + + - [qMRLab](https://github.com/qMRLab/qMRLab/wiki/Guideline:-Generating-Documentation) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..922152e9 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..8d7a63fb --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +Sphinx +sphinxcontrib-matlabdomain +sphinxcontrib-napoleon +sphinx_rtd_theme diff --git a/docs/source/_static/cpp_lab_logo.png b/docs/source/_static/cpp_lab_logo.png new file mode 100644 index 00000000..89277c01 Binary files /dev/null and b/docs/source/_static/cpp_lab_logo.png differ diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..eebcb246 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,80 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +sys.path.insert(0, os.path.abspath('../..')) + +# -- Project information ----------------------------------------------------- + +project = 'CPP_PTB' +copyright = '2020, CPP_PTB developers' +author = 'CPP_PTB developers' + +# The full version, including alpha/beta/rc tags +release = 'v1.0.0' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinxcontrib.matlab', + 'sphinx.ext.autodoc'] +matlab_src_dir = os.path.dirname(os.path.abspath('../../src')) +primary_domain = 'mat' + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +html_logo = '_static/cpp_lab_logo.png' + +# html_theme_options = { +# 'github_user': 'cpp-lln-lab', +# 'github_repo': 'CPP_BIDS_SPM_pipeline', +# 'github_button': True, +# 'github_banner': True +# } +# html_theme_options = { +# 'collapse_navigation': False, +# 'display_version': False, +# 'navigation_depth': 4, +# } + +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', # needs 'show_related': True theme option to display + 'searchbox.html', + 'donate.html', + ] +} diff --git a/docs/source/function_description.rst b/docs/source/function_description.rst new file mode 100644 index 00000000..c9457214 --- /dev/null +++ b/docs/source/function_description.rst @@ -0,0 +1,122 @@ +Function description +==================== + +The functions of our pipeline + +---- + +List of functions in the ``src`` folder. + +.. module:: src + +.. autofunction:: initPTB +.. autofunction:: drawFieldOfVIew +.. autofunction:: eyeTracker +.. autofunction:: getExperimentEnd +.. autofunction:: getExperimentStart +.. autofunction:: isOctave +.. autofunction:: readAndFilterLogfile +.. autofunction:: waitForTrigger +.. autofunction:: waitFor + +---- + +List of functions in the ``src/aperture`` folder. + +.. module:: src.aperture + +.. autofunction:: apertureTexture +.. autofunction:: eccenLogSpeed +.. autofunction:: getApertureName +.. autofunction:: saveAperture +.. autofunction:: saveApertures +.. autofunction:: smoothOval +.. autofunction:: smoothRect + +---- + +List of functions in the ``src/dot`` folder. + +.. module:: src.dot + +.. autofunction:: computeCartCoord +.. autofunction:: computeRadialMotionDirection +.. autofunction:: decomposeMotion +.. autofunction:: dotMotionSimulation +.. autofunction:: dotTexture +.. autofunction:: generateNewDotPositions +.. autofunction:: initDots +.. autofunction:: reseedDots +.. autofunction:: seedDots +.. autofunction:: setDotDirection +.. autofunction:: updateDots + +---- + +List of functions in the ``src/errors`` folder. + +.. module:: src.errors + +.. autofunction:: errorAbort +.. autofunction:: errorAbortGetReponse +.. autofunction:: errorDistanceToScreen +.. autofunction:: errorRestrictedKeysGetReponse + +---- + +List of functions in the ``src/fixation`` folder. + +.. module:: src.fixation + +.. autofunction:: drawFixation +.. autofunction:: initFixation + +---- + +List of functions in the ``src/keyboard`` folder. + +.. module:: src.keyboard + +.. autofunction:: getResponse +.. autofunction:: checkAbort +.. autofunction:: checkAbortGetResponse +.. autofunction:: collectAndSaveResponses +.. autofunction:: pressSpaceForMe +.. autofunction:: testKeyboards + +---- + +List of functions in the ``src/randomization`` folder. + +.. module:: src.randomization + +.. autofunction:: repeatShuffleConditions +.. autofunction:: setTargetPositionInSequence +.. autofunction:: shuffle + +---- + +List of functions in the ``src/screen`` folder. + +.. module:: src.screen + +.. autofunction:: farewellScreen +.. autofunction:: standByScreen + +---- + +List of functions in the ``src/utils`` folder. + +.. module:: src.utils + +.. autofunction:: checkPtbVersion +.. autofunction:: cleanUp +.. autofunction:: computeFOV +.. autofunction:: degToPix +.. autofunction:: makeGif +.. autofunction:: pixToDeg +.. autofunction:: printCreditsCppPtb +.. autofunction:: printScreen +.. autofunction:: setDefaults +.. autofunction:: setDefaultsPTB +.. autofunction:: setUpRand diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..fdf5f403 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,27 @@ +.. CPP_PTB documentation master file, created by + sphinx-quickstart on Sun Oct 25 14:42:27 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to CPP_PTB's documentation! +=================================== + +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 their reuse (#DontRepeatYourself) + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + installation + function_description + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 00000000..6e2e1af4 --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,144 @@ +************ +Installation +************ + +Requirements +============ + +Make sure that the following toolboxes are installed and added to the matlab / +octave path. + +For instructions see the following links: + ++------------------------------------------------------------+--------------+ +| Requirements | Used version | ++============================================================+==============+ +| `PsychToolBox `_ | >=3.0.14 | ++------------------------------------------------------------+--------------+ +| `Matlab `_ | >=2015b | ++------------------------------------------------------------+--------------+ +| or `Octave `_ | 4.? | ++------------------------------------------------------------+--------------+ + +Tested: + +- matlab 2015b or octave 4.2.2 and PTB 3.0.14. + +How to install +============== + +The easiest way to use this repository is to create a new repository by using +the +`template PTB experiment repository `_: +this creates a new repository on your github account with all the basic folders, +files and submodules already set up. You only have to then clone the repository +and you are good to go. + +Download with git +***************** + +.. code-block:: bash + :linenos: + + 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 + + +Then get the latest commit to stay up to date: + +.. code-block:: bash + :linenos: + + # 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 + +.. code-block:: bash + :linenos: + + # 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 + + +Add as a submodule +****************** + +Add it as a submodule in the repo you are working on. + +.. code-block:: bash + :linenos: + + 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 + +To get the latest commit you then need to update the submodule with the +information on its remote repository and then merge those locally. + +.. code-block:: bash + :linenos: + + git submodule update --remote --merge + +Remember that updates to submodules need to be committed as well. + +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): + +.. code-block:: bash + :linenos: + + git clone --recurse-submodules https://github.com/user_name/yourExperiment.git + +This would be the way to do it "by hand" + +.. code-block:: bash + :linenos: + + # clone the repo + git clone https://github.com/user_name/yourExperiment.git + + # go into the directory + cd yourExperiment + + # initialize and get the content of the first level of submodules (CPP_PTB and CPP_BIDS) + git submodule init + git submodule update + + # get the nested submodules JSONio and BIDS-matlab for CPP_BIDS + git submodule foreach --recursive 'git submodule init' + git submodule foreach --recursive 'git submodule update' + +Direct download +*************** + +Download the code. Unzip. And add to the matlab path. + +Pick a specific version from `here `_. + +Or take `the latest commit `_ - +NOT RECOMMENDED. + +Add CPP_PTB globally to the matlab path +*************************************** + +This is NOT RECOMMENDED as this might create conflicts if you use different +versions of CPP_PTB as sub-modules. + +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: + +.. code-block:: bash + :linenos: + + # from within the CPP_PTB folder + matlab -nojvm -nosplash -r "addpath(genpath(fullfile(pwd, 'src'))); savepath(); path(); exit();"