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

* feature: post hardware information to alyx
* generate PDF documentation
* increase verbosity of error handling in base task
* remove dead code

.github/workflows/documentation.yaml

@@ -7,6 +7,7 @@ on:
     paths:
       - '.github/workflows/documentation.yaml'
       - 'docs/**'
+      - 'iblrig/__init__.py'
       - 'CHANGELOG.md'
       - 'README.md'
       - 'pyproject.toml'
@@ -20,13 +21,12 @@ jobs:
       - name: Set up PDM
         uses: pdm-project/setup-pdm@v4
         with:
-          python-version: ${{ matrix.python-version }}
           cache: true
+          python-version-file: pyproject.toml
       - name: Install requirements
         run: pdm sync -dG doc
       - name: Sphinx build
-        run: |
-          pdm run sphinx-build docs/source docs/build/html
+        run: pdm run sphinx-build docs/source docs/build/html
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3
         with:

.github/workflows/release.yaml

@@ -0,0 +1,44 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - iblrigv8
+    tags:
+      - '[0-9]+.[0-9]+.[0-9]+'
+
+jobs:
+  pdf:
+    name: Build PDF
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up PDM
+        uses: pdm-project/setup-pdm@v4
+        with:
+          cache: true
+          python-version-file: pyproject.toml
+      - name: Install requirements
+        run: pdm sync -dG doc
+      - name: Build PDF
+        run: pdm run make -C docs/ simplepdf
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: documentation
+          path: docs/build/simplepdf/*.pdf
+          retention-days: 1
+
+  release:
+    name: Publish GitHub Release
+    needs: pdf
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Download artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: documentation
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: documentation/*.pdf

CHANGELOG.md

@@ -1,6 +1,13 @@
 Changelog
 =========
 
+8.23.1
+------
+* feature: post hardware information to alyx
+* generate PDF documentation
+* increase verbosity of error handling in base task
+* remove dead code
+
 8.23.0
 ------
 * hardware validation: check for unexpected events on Bpod's digital input ports

docs/source/conf.py

@@ -1,16 +1,18 @@
 from datetime import date
 
 from iblrig import __version__
+from iblrig.constants import BASE_PATH
 
 project = 'iblrig'
 copyright = f'2018 – {date.today().year} International Brain Laboratory'
 author = 'International Brain Laboratory'
 version = '.'.join(__version__.split('.')[:3])
+release = '.'.join(__version__.split('.')[:3])
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['sphinx_lesson', 'sphinx.ext.autosectionlabel']
+extensions = ['sphinx_lesson', 'sphinx.ext.autosectionlabel', 'sphinx_simplepdf']
 autosectionlabel_prefix_document = True
 source_suffix = ['.rst', '.md']
 
@@ -23,3 +25,17 @@
 
 html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']
+
+
+simplepdf_vars = {
+    'primary': '#004f8c',
+    'secondary': '#004f8c',
+    'cover': 'white',
+    'cover-bg': 'linear-gradient(180deg, #004f8c 0%, #00a1d9 50%, #cc3399 100%)',
+}
+simplepdf_file_name = f'iblrig_{__version__}_reference.pdf'
+simplepdf_weasyprint_flags = ['-j70', '-D150', '--hinting']
+html_context = {
+    'docs_scope': 'external',
+    'cover_meta_data': 'International Brain Laboratory',
+}

docs/source/index.rst

@@ -1,8 +1,10 @@
-.. include:: ../../README.md
-   :parser: myst_parser.sphinx_
+.. if-builder:: html
+
+   .. include:: ../../README.md
+      :parser: myst_parser.sphinx_
 
 .. toctree::
-   :caption: Contents:
+   :maxdepth: 3
    :hidden:
 
    installation
@@ -12,14 +14,16 @@
    reference_developer_guide
    faq
 
-.. toctree::
-   :hidden:
+.. if-builder:: html
 
-   changelog
+   .. toctree::
+      :hidden:
 
-.. toctree::
-   :caption: Links
-   :hidden:
+      changelog
+
+   .. toctree::
+      :caption: Links
+      :hidden:
 
-   IBLRIG on GitHub <https://github.com/int-brain-lab/iblrig>
-   Appendix 3: IBL protocol for setting up the behavioral training rig <https://doi.org/10.6084/m9.figshare.11634732>
+      IBLRIG on GitHub <https://github.com/int-brain-lab/iblrig>
+      Appendix 3: IBL protocol for setting up the behavioral training rig <https://doi.org/10.6084/m9.figshare.11634732>

docs/source/installation.rst

@@ -49,8 +49,8 @@ Now, run the following command at the prompt of Windows PowerShell:
    and usability.
 
 
-Installing MS Visual C++ Redistributable
-----------------------------------------
+Installing Visual C++ Redistributable
+-------------------------------------
 
 With the Administrator PowerShell still open, run the following commands:
 
@@ -67,7 +67,7 @@ With the Administrator PowerShell still open, run the following commands:
 .. admonition:: Background
    :class: seealso
 
-   These commands will create a temporary directory, download and silently install the Visual C++ Redistributable package for
+   These commands will create a temporary directory, download and install the Visual C++ Redistributable package for
    64-bit Windows systems. The installer is retrieved from a Microsoft server and executed with parameters to ensure a seamless
    and unobtrusive installation process.
 

docs/source/reference_developer_guide.rst

@@ -5,7 +5,7 @@ Developer Guide
 Versioning Scheme
 -----------------
 
-IBLRIG v8 uses `Semantic Versioning 2.0.0 <https://semver.org/spec/v2.0.0.html>`_.
+IBLRIG v8 uses `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.
 Its version string (currently "|version|") is a combination of three fields, separated by dots:
 
 .. centered:: ``MAJOR`` . ``MINOR`` . ``PATCH``
@@ -32,18 +32,21 @@ Here,
 * ``post3`` indicates the third unversioned commit after the latest versioned release, and
 * ``dirty`` indicates the presence of uncommited changes in your local repository of IBLRIG.
 
-Both of these fields are inferred by means of git describe and do not require manual interaction from the developer.
+Both of these fields are automatically inferred (by means of ``git describe``) and do not require manual interaction from the
+developer.
 
 
-PDM
----
+Package Management and Development Workflows with PDM
+-----------------------------------------------------
 
 We use `PDM <https://pdm-project.org/en/latest/>`_ to manage dependencies of IBLRIG.
-See `PDM's documentation <https://pdm-project.org/en/latest/#installation>` for help with installing PDM.
+PDM can also be used to run various commands with relevance to the development process without having to activate a virtual
+environment first.
+Please refer to `PDM's documentation <https://pdm-project.org/en/latest/#installation>`_ for help with installing PDM.
 
 
 Installing Developer Dependencies
----------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 To install additional dependencies needed for working on IBLRIG's code-base, run:
 
@@ -52,45 +55,39 @@ To install additional dependencies needed for working on IBLRIG's code-base, run
    pdm sync -d
 
 
-Running Unit Tests Locally
---------------------------
+Running Unit Tests
+^^^^^^^^^^^^^^^^^^
 
 To run unit tests locally, run:
 
 .. code-block:: console
 
    pdm run pytest
 
-This will also generate a coverage report which can be found in the ``htmlcov`` directory.
+This will also generate a HTML based coverage report which can be found in the ``htmlcov`` directory.
 
 
 Linting & Formatting
---------------------
-
-To lint your code, run the:
-
-.. code-block:: console
+^^^^^^^^^^^^^^^^^^^^
 
-   pdm run ruff check
+We use `Ruff <https://docs.astral.sh/ruff>`_ for linting and formatting our code-base in close accordance with `the Black code
+style <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`_.
 
-Adding the commandline flag ``--fix`` will automatically fix issues that are deemed safe to handle:
+To lint your code, run:
 
 .. code-block:: console
 
-   pdm run ruff check --fix
-
-To *check* if your code conforms to the `Black code style <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`_, run:
-
-.. code-block:: console
+   pdm run ruff check
 
-   pdm run ruff format --check
+Appending the flag ``--fix`` to the above command will automatically fix issues that are deemed safe to handle.
 
-To reformat your code according to the `Black code style <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`_, run:
+To reformat your code according to the `Black code style <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`_ run:
 
 .. code-block:: console
 
    pdm run ruff format
 
+Appending the flag ``--check`` to the above command will check your code for formatting issues without applying any changes.
 Refer to `Ruff Formater's documentation <https://docs.astral.sh/ruff/formatter/>`_ for further details.
 
 
@@ -115,18 +112,29 @@ Release Checklist
 Building the documentation
 --------------------------
 
+To build the documentation, run:
+
 .. code-block:: console
 
    pdm run sphinx-autobuild ./docs/source ./docs/build
 
+You can also export the documentation to a PDF file:
+
+.. code-block:: console
+
+   pdm run make -C docs/ simplepdf
+
+Find the exported PDF file in ``docs/build/simplepdf``.
+
 
 Contribute to the documentation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 To write the documentation:
 
 * Write the documentation in the ``iblrig/docs/source`` folder
 * If you are writing in a new file, add it to the ``index.rst`` so it appears in the table of content
-* Push all your changes to the ``iblrigv8dev`` branch ; if this branch does not exist, create it first
+* Push all your changes to the ``iblrigv8dev`` branch; if this branch does not exist, create it first
 
 To release the documentation onto the `website <https://int-brain-lab.github.io/iblrig>`_:
 

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.0'
+__version__ = '8.23.1'
 
 
 from iblrig.version_management import get_detailed_version_string

iblrig/base_choice_world.py

@@ -676,21 +676,32 @@ def trial_completed(self, bpod_data):
         # get the trial outcome
         state_names = ['correct', 'error', 'no_go', 'omit_correct', 'omit_error', 'omit_no_go']
         raw_outcome = {sn: ~np.isnan(bpod_data['States timestamps'].get(sn, [[np.NaN]])[0][0]) for sn in state_names}
-        outcome = next(k for k in raw_outcome if raw_outcome[k])
-        # Update response buffer -1 for left, 0 for nogo, and 1 for rightward
-        position = self.trials_table.at[self.trial_num, 'position']
-        if 'correct' in outcome:
-            self.trials_table.at[self.trial_num, 'trial_correct'] = True
-            self.session_info.NTRIALS_CORRECT += 1
-            self.trials_table.at[self.trial_num, 'response_side'] = -np.sign(position)
-        elif 'error' in outcome:
-            self.trials_table.at[self.trial_num, 'response_side'] = np.sign(position)
-        elif 'no_go' in outcome:
-            self.trials_table.at[self.trial_num, 'response_side'] = 0
-        super().trial_completed(bpod_data)
-        # here we throw potential errors after having written the trial to disk
-        assert np.sum(list(raw_outcome.values())) == 1
-        assert position != 0, 'the position value should be either 35 or -35'
+        try:
+            outcome = next(k for k in raw_outcome if raw_outcome[k])
+            # Update response buffer -1 for left, 0 for nogo, and 1 for rightward
+            position = self.trials_table.at[self.trial_num, 'position']
+            if 'correct' in outcome:
+                self.trials_table.at[self.trial_num, 'trial_correct'] = True
+                self.session_info.NTRIALS_CORRECT += 1
+                self.trials_table.at[self.trial_num, 'response_side'] = -np.sign(position)
+            elif 'error' in outcome:
+                self.trials_table.at[self.trial_num, 'response_side'] = np.sign(position)
+            elif 'no_go' in outcome:
+                self.trials_table.at[self.trial_num, 'response_side'] = 0
+            super().trial_completed(bpod_data)
+            # here we throw potential errors after having written the trial to disk
+            assert np.sum(list(raw_outcome.values())) == 1
+            assert position != 0, 'the position value should be either 35 or -35'
+        except StopIteration as e:
+            log.error(f'No outcome detected for trial {self.trial_num}.')
+            log.error(f'raw_outcome: {raw_outcome}')
+            log.error('State names: ' + ', '.join(bpod_data['States timestamps'].keys()))
+            raise e
+        except AssertionError as e:
+            log.error(f'Assertion Error in trial {self.trial_num}.')
+            log.error(f'raw_outcome: {raw_outcome}')
+            log.error('State names: ' + ', '.join(bpod_data['States timestamps'].keys()))
+            raise e
 
 
 class BiasedChoiceWorldSession(ActiveChoiceWorldSession):

iblrig/gui/wizard.py

@@ -47,7 +47,7 @@
 from iblrig.path_helper import load_pydantic_yaml
 from iblrig.pydantic_definitions import HardwareSettings, RigSettings
 from iblrig.raw_data_loaders import load_task_jsonable
-from iblrig.tools import alyx_reachable, internet_available
+from iblrig.tools import alyx_reachable, get_lab_location_dict, internet_available
 from iblrig.valve import Valve
 from iblrig.version_management import check_for_updates, get_changelog
 from iblutil.util import Bunch, setup_logger
@@ -229,7 +229,12 @@ def login(
 
         # validate connection and some parameters now that we're connected
         try:
-            self.alyx.rest('locations', 'read', id=self.hardware_settings.RIG_NAME)
+            self.alyx.rest(
+                'locations',
+                'partial_update',
+                id=self.hardware_settings.RIG_NAME,
+                data={'json': get_lab_location_dict(self.hardware_settings, self.iblrig_settings)},
+            )
         except HTTPError as ex:
             if ex.response.status_code not in (404, 400):  # file not found; auth error
                 # Likely Alyx is down or server-side issue