8.24.0

.github/workflows/release.yaml

@@ -2,8 +2,6 @@ name: Release
 
 on:
  push:
- branches:
- - iblrigv8
  tags:
  - '[0-9]+.[0-9]+.[0-9]+'
 
@@ -41,4 +39,4 @@ jobs:
  name: documentation
  - uses: softprops/action-gh-release@v2
  with:
- files: documentation/*.pdf
+ files: iblrig_*_reference.pdf

.gitignore

@@ -46,3 +46,4 @@ devices/camera_recordings/*.layout
 .pdm-python
 /dist
 *~
+docs/source/api/*

CHANGELOG.md

@@ -1,6 +1,18 @@
 Changelog
 =========
 
+8.24.0
+------
+* feature: validate values in `trials_table` using Pydantic
+* feature: add auto-generated API reference to documentation
+* changed: `show_trial_log()` now accepts a dict for including additional log items
+* fix: `_ephysChoiceWorld` - values from the pre-generated sessions were not actually used 
+* fix: `_ephysChoiceWorld` - trial fixtures contained inverted values for `probability_left`
+* fix: GUI - Subjects and Projects are not being cached
+* add script for validating audio output of Bpod HiFi Module (in `scripts/` folder)
+
+-------------------------------
+
 8.23.1
 ------
 * feature: post hardware information to alyx

docs/source/_templates/custom-class-template.rst

@@ -0,0 +1,12 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. inheritance-diagram:: {{ objname }}
+ :parts: 1
+
+|
+
+.. autoclass:: {{ objname }}
+ :members:
+ :undoc-members:

docs/source/_templates/custom-module-template.rst

@@ -0,0 +1,84 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+ {% block attributes %}
+ {%- if attributes %}
+ .. rubric:: {{ _('Module Attributes') }}
+
+ .. autosummary::
+ :nosignatures:
+ :toctree:
+ {% for item in attributes %}
+ {{ item }}
+ {%- endfor %}
+ {% endif %}
+ {%- endblock %}
+
+ {%- block functions %}
+ {%- if functions %}
+ .. rubric:: {{ _('Functions') }}
+
+ .. autosummary::
+ :nosignatures:
+ :toctree:
+ {% for item in functions %}
+ {{ item }}
+ {%- endfor %}
+ {% endif %}
+ {%- endblock %}
+
+ {%- block classes %}
+ {%- if classes %}
+ .. rubric:: {{ _('Classes') }}
+
+ .. autosummary::
+ :nosignatures:
+ :toctree:
+ :template: custom-class-template.rst
+ {% for item in classes %}
+ {{ item }}
+ {%- endfor %}
+ {% endif %}
+ {%- endblock %}
+
+ {%- block exceptions %}
+ {%- if exceptions %}
+ .. rubric:: {{ _('Exceptions') }}
+
+ .. autosummary::
+ :nosignatures:
+ :toctree:
+ {% for item in exceptions %}
+ {{ item }}
+ {%- endfor %}
+ {% endif %}
+ {%- endblock %}
+
+{%- block modules %}
+{%- if modules or name == 'iblrig_tasks' %}
+.. rubric:: Modules
+
+.. autosummary::
+ :nosignatures:
+ :toctree:
+ :template: custom-module-template.rst
+ :recursive:
+{% for item in modules %}
+ {%- if item != 'test' %} {# EXCLUDE TESTS FROM API #}
+ {{ item }}
+ {% endif %}
+{%- endfor %}
+{%- if name == 'iblrig_tasks' %}
+ _iblrig_tasks_advancedChoiceWorld
+ _iblrig_tasks_biasedChoiceWorld
+ _iblrig_tasks_ephysChoiceWorld
+ _iblrig_tasks_habituationChoiceWorld
+ _iblrig_tasks_ImagingChoiceWorld
+ _iblrig_tasks_neuroModulatorChoiceWorld
+ _iblrig_tasks_passiveChoiceWorld
+ _iblrig_tasks_spontaneous
+ _iblrig_tasks_trainingChoiceWorld
+ _iblrig_tasks_trainingPhaseChoiceWorld
+{% endif %}
+{% endif %}
+{%- endblock %}

docs/source/api.rst

@@ -0,0 +1,10 @@
+API Reference
+=============
+
+.. autosummary::
+ :toctree: api
+ :template: custom-module-template.rst
+ :recursive:
+
+ iblrig
+ iblrig_tasks

docs/source/conf.py

@@ -1,7 +1,10 @@
+import os
+import sys
 from datetime import date
 
+sys.path.insert(0, os.path.abspath('../..'))
 from iblrig import __version__
-from iblrig.constants import BASE_PATH
+
 
 project = 'iblrig'
 copyright = f'2018 – {date.today().year} International Brain Laboratory'
@@ -12,21 +15,41 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['sphinx_lesson', 'sphinx.ext.autosectionlabel', 'sphinx_simplepdf']
+templates_path = ['_templates']
+extensions = [
+ 'sphinx_lesson',
+ 'sphinx.ext.autosectionlabel',
+ 'sphinx_simplepdf',
+ 'sphinx.ext.intersphinx',
+ 'sphinx.ext.napoleon',
+ 'sphinx.ext.autodoc',
+ 'sphinx.ext.autosummary',
+ 'sphinx.ext.inheritance_diagram',
+ 'sphinx.ext.viewcode',
+]
 autosectionlabel_prefix_document = True
 source_suffix = ['.rst', '.md']
-
-templates_path = ['_templates']
 exclude_patterns = []
-
+intersphinx_mapping = {
+ 'python': ('https://docs.python.org/3', None),
+ 'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+ 'matplotlib': ('https://matplotlib.org/stable/', None),
+ 'numpy': ('https://numpy.org/doc/stable/', None),
+ 'pandas': ('https://pandas.pydata.org/docs/', None),
+ 'scipy': ('https://docs.scipy.org/doc/scipy/', None),
+ 'one:': ('https://int-brain-lab.github.io/ONE/', None),
+ 'pydantic': ('https://docs.pydantic.dev/latest/', None),
+ 'iblenv': ('https://int-brain-lab.github.io/iblenv/', None),
+ 'pyserial': ('https://pyserial.readthedocs.io/en/latest/', None),
+ 'Sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+}
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'sphinx_rtd_theme'
-html_static_path = ['_static']
-
 
+# -- Options for PDF creation ------------------------------------------------
 simplepdf_vars = {
  'primary': '#004f8c',
  'secondary': '#004f8c',
@@ -39,3 +62,31 @@
  'docs_scope': 'external',
  'cover_meta_data': 'International Brain Laboratory',
 }
+
+# -- Settings for automatic API generation -----------------------------------
+autodoc_mock_imports = ["PySpin"]
+autodoc_class_signature = 'separated' # 'mixed', 'separated'
+autodoc_member_order = 'groupwise' # 'alphabetical', 'groupwise', 'bysource'
+autodoc_inherit_docstrings = False
+autodoc_typehints = 'description' # 'description', 'signature', 'none', 'both'
+autodoc_typehints_description_target = 'all' # 'all', 'documented', 'documented_params'
+autodoc_typehints_format = 'short' # 'fully-qualified', 'short'
+
+autosummary_generate = True
+autosummary_imported_members = False
+
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = True
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = False
+napoleon_use_admonition_for_examples = True
+napoleon_use_admonition_for_notes = True
+napoleon_use_admonition_for_references = True
+napoleon_use_ivar = False
+napoleon_use_param = False
+napoleon_use_rtype = True
+napoleon_use_keyword = True
+napoleon_preprocess_types = True
+napoleon_type_aliases = None
+napoleon_attr_annotations = False

docs/source/faq.rst

@@ -37,11 +37,13 @@ Sound Issues
 
 * Is ``hardware_settings.yaml`` set up correctly? Valid options for sound ``OUTPUT`` are:
 
+ - ``hifi``,
  - ``harp``,
  - ``xonar``, or
  - ``sysdefault``.
 
  Make sure that this value matches the actual soundcard used on your rig.
+ Note that ``sysdefault`` is only used in test scenarios and should not be used during actual experiments.
 
 
 Screen Issues

docs/source/index.rst

@@ -19,6 +19,7 @@
  .. toctree::
  :hidden:
 
+ api
  changelog
 
  .. toctree::

docs/source/reference_write_your_own_task.rst

@@ -8,13 +8,13 @@ During the lifetime of the IBL project, we realized that multiple task variants
 
 This left us with the only option of developing a flexible task framework through hierarchical inheritance.
 
-All tasks inherit from the ``iblrig.base_tasks.BaseSession`` class, which provides the following functionalities:
+All tasks inherit from the :class:`iblrig.base_tasks.BaseSession` class, which provides the following functionalities:
  - read hardware parameters and rig parameters
  - optionally interfaces with the `Alyx experimental database <https://github.com/cortex-lab/alyx>`_
  - creates the folder structure for the session
- - writes the task and rig parameters, log, and :doc:`acquisition description files <../description_file>`
+ - writes the task and rig parameters, log, and :doc:`acquisition description files <../reference_description_file>`
 
-Additionally the ``iblrig.base_tasks`` module provides "hardware mixins". Those are classes that provide hardware-specific functionalities, such as connecting to a Bpod or a rotary encoder. They are composed with the ``BaseSession`` class to create a task.
+Additionally the :mod:`iblrig.base_tasks` module provides "hardware mixins". Those are classes that provide hardware-specific functionalities, such as connecting to a Bpod or a rotary encoder. They are composed with the :class:`~.iblrig.base_tasks.BaseSession` class to create a task.
 
 .. warning::
 
@@ -33,21 +33,21 @@ What Happens When Running an IBL Task?
  - Reading of task parameters.
  - Instantiation of hardware mixins.
 
-2. The task initiates the ``run()`` method. Prior to execution, this
+2. The task initiates the :meth:`~.iblrig.base_tasks.run` method. Prior to execution, this
  method:
 
  - Launches the hardware modules.
  - Establishes a session folder.
  - Saves the parameters to disk.
 
-3. The experiment unfolds: the ``run()`` method triggers the ``_run()``
+3. The experiment unfolds: the :meth:`~.iblrig.base_tasks.run` method triggers the ``_run()``
  method within the child class:
 
  - Typically, this involves a loop that generates a Bpod state
  machine for each trial and runs it.
 
 4. Upon SIGINT or when the maximum trial count is reached, the
- experiment concludes. The end of the ``run()`` method includes:
+ experiment concludes. The end of the :meth:`~.iblrig.base_tasks.run` method includes:
 
  - Saving the final parameter file.
  - Recording administered water and session performance on Alyx.

iblrig/__init__.py

@@ -6,7 +6,7 @@
 # 5) git tag the release in accordance to the version number below (after merge!)
 # >>> git tag 8.15.6
 # >>> git push origin --tags
-__version__ = '8.23.1'
+__version__ = '8.24.0'
 
 
 from iblrig.version_management import get_detailed_version_string