Merge pull request #711 from int-brain-lab/iblrigv8dev

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