Distinguish between Device Group & Device properties (#223)

cjsha · jonnew · web-flow · commit a8c83d00fd17 · 2025-03-06T23:27:17.000-05:00
Distinguish between Device & Device Group properties - This is done on the OpenEphys.Onix1 overview page - "Aggregate", "Multi-Device" -> "Device Group" - Add css classes for badges - Define what devices are on the configuration operator pages - I wanted to link to properties in the tables which motivated me to fix the xref issue #70. This fix seems to work well enough for now. That's what the changes are related to in the .js files are concerning. - Reduce excessive formatting (specifically hyperlinks don't need to be wrapped in back ticks) - Remove comments that appear in HTML inspector Co-authored-by: jonnew <jpn@open-ephys.org>
diff --git a/api/configure.md b/api/configure.md
@@ -1,9 +1,14 @@
 ---
 uid: configure
-title: Configuration Operators
+title: Device Group Configuration Operators
 ---
 
-Aggregate configuration operators belong in a top-level chain of operators between
-[`CreateContext`](xref:OpenEphys.Onix1.CreateContext) and [`StartAcquisition`](xref:OpenEphys.Onix1.StartAcquisition) to
-configure ONIX hardware hubs. These are known as aggregate configuration operators because they configure an aggregation
-of devices (also referred to as a hub) on a given headstage, miniscope, breakout board, etc..
+Device Group configuration operators belong in a top-level configuration chain between
+[CreateContext](xref:OpenEphys.Onix1.CreateContext) and
+[StartAcquisition](xref:OpenEphys.Onix1.StartAcquisition) to configure ONIX hardware. These are
+known as Device Group configuration operators because they configure a group of devices on a given
+headstage, miniscope, breakout board, etc. Devices represent physical element
+interfacing with the environment (e.g., an external sensor with a digital
+communication interface like the BNO055, Neuropixels probes, or RHS2116 stimulus
+trigger) or internal data sources (e.g., a controller based digital logic module
+that generates system status reports like the port status controller).
diff --git a/api/device-configure.md b/api/device-configure.md
@@ -4,8 +4,21 @@ title: Device Configuration Operators
 ---
 
 > [!TIP]
->  Device configuration operators are not recommended for using off-the-shelf Open Ephys hardware. Use aggregate [configuration operators](xref:configure) instead. Aggregate [configuration operators](xref:configure) confer the following benefits:
-> - The `address` and `name` properties of aggregate configuration operators undergo automatic configuration which reduces the risk of erroneous configuration.
-> - The workflow is less cluttered with configuration operators as one aggregate configuration operator corresponds to multiple device operators. This improves workflow legibility and expedites the workflow scripting process.
+>  Device configuration operators are not recommended for using off-the-shelf
+>  Open Ephys hardware. Use [Device Group configuration
+>  operators](xref:configure) instead. They confer the following benefits:
+> - The `address` and `name` properties of Device Group configuration operators
+>   undergo automatic configuration which reduces the risk of erroneous
+>   configuration.
+> - The workflow is less cluttered with configuration operators as one Device
+>   Group configuration operator corresponds to multiple device operators. This
+>   improves workflow legibility and expedites the workflow scripting process.
 
-Device configuration operators belong in a top-level chain of operators between [`CreateContext`](xref:OpenEphys.Onix1.CreateContext) and [`StartAcquisition`](xref:OpenEphys.Onix1.StartAcquisition) to configure devices contained by ONIX hardware hubs.
+Device configuration operators belong in a top-level configuration chain between
+[CreateContext](xref:OpenEphys.Onix1.CreateContext) and
+[StartAcquisition](xref:OpenEphys.Onix1.StartAcquisition) to configure devices
+that can be found on ONIX hardware. Devices represent physical element
+interfacing with the environment (e.g., an external sensor with a digital
+communication interface like the BNO055, Neuropixels probes, or RHS2116 stimulus
+trigger) or internal data sources (e.g., a controller based digital logic module
+that generates system status reports like the port status controller).
diff --git a/api/overview.md b/api/overview.md
@@ -1,34 +1,61 @@
 ---
 uid: OpenEphys.Onix1
-title: OpenEphys.Onix1
+title: Library Reference
 ---
 
-> [!TIP]
-> Quickly access these pages in Bonsai by pressing <kbd>F1</kbd> while an OpenEphys.Onix1 operator
-> is selected in the workflow or Toolbox. 
+[OpenEphys.Onix1](https://github.com/open-ephys/bonsai-onix1) is a Bonsai
+package that exposes a set of Bonsai Operators for control of and data
+acquisition from ONIX hardware. This library reference that documents each of
+the operators available in the package in a standardized format. This reference
+is generated from the [source code](https://github.com/open-ephys/bonsai-onix1).
 
-OpenEphys.Onix1 is a Bonsai package for control of and data acquisition from ONIX hardware. This
-section of the docs is dedicated to facilitate construction of workflows using OpenEphys.Onix1. It
-contains helpful information about OpenEphys.Onix1 operators and the data elements they produce.
-such as in-depth descriptions of their properties and their data types. The data elements produced
-by OpenEphys.Onix1 operators where you can find information such as equations for converting
-electrophysiology signals from the DAC step-size to volts. Take the
-<xref:OpenEphys.Onix1.Rhs2116DataFrame> for example.
+> [!TIP]
+> You can access the reference for a particular operator from within the Bonsai
+> editor pressing <kbd>F1</kbd> while an OpenEphys.Onix1 operator is selected in
+> the workflow or Toolbox.
 
 ## Property Categories
+The behavior of Bonsai operators is governed by their "Properties".
+Properties can be viewed and changed using Property Editor on the right side of
+the workflow:
+
+![Bonsai property editor](../images/properties-pane.webp){width=650px}
+
+Properties in this library fall into several categories which are useful for
+distinguishing when a property change will be applied to hardware and the scope
+of the property's effect. The following tags are used throughout the
+documentation designate these property categories:
 
-In the OpenEphys.Onix1 package, properties belong to specific categories that define when the
-property effects the hardware. 
+<span class="badge oe-badge-border oe-badge-yellow"
+id="configuration">Configuration</span> properties have an effect on hardware
+when a workflow is started and are used to initialize the hardware state. If
+they are changed while a workflow is running, they will not have an effect until
+the workflow is restarted. For example, CreateContext's
+<xref:OpenEphys.Onix1.CreateContext.Index> Configuration property is used to
+specify the hardware prior to starting a recording, and editing this property
+has no effect until the workflow is started or restarted.
 
-<span class="badge bg-warning-subtle border border-warning-subtle text-warning-emphasis rounded-pill"
-id="configuration">configuration</span> properties have an effect on hardware when a workflow is started and are used to
-initialize the hardware state. Even if they are changed while a workflow is running, they will not have an effect until
-the workflow is restarted.
+<span class="badge oe-badge-border oe-badge-blue"
+id="acquisition">Acquisition</span> properties have an immediate effect on
+hardware when the workflow is running. For example, the
+<xref:OpenEphys.Onix1.Headstage64ElectricalStimulatorTrigger.InterPulseInterval>
+property allows dynamically configuring the duration between electrical
+stimulation pulses. Along with its other Acquisition properties, the entire
+electrical stimulation pattern can be modulated in real-time while the workflow
+is running.
 
-<span class="badge bg-primary-subtle border border-primary-subtle text-primary-emphasis rounded-pill"
-id="acquisition">acquisition</span> properties have an immediate effect on hardware when the workflow is running. For
-instance, stimulus waveform properties can be dynamically modified according to parameters in your workflow.
+<span class="badge oe-badge-border oe-badge-green" id="device-group">Device
+Group</span> properties are only available through [Device Group configuration
+operators](xref:configure). These properties are used to configure a group of
+devices. For example, ConfigureNeuropixelsV2eHeadstage's
+<xref:OpenEphys.Onix1.ConfigureHeadstageNeuropixelsV2e.Port> property
+configures the port name for all devices on the NeuropixelsV2e Headstage (which
+in turn automatically configures each device's address).
 
-`Devices` properties refer to the individual devices available within a particular aggregate operator. Aggregate
-operators include <xref:OpenEphys.Onix1.ConfigureHeadstage64>, <xref:OpenEphys.Onix1.ConfigureBreakoutBoard>, and more.
-Explore other available options under the [aggregate configuration operators](xref:configure) page.
+<span class="badge oe-badge-border oe-badge-purple" id="device">Device</span>
+properties are available through [Device configuration
+operators](xref:device-configure) and Device Group configuration operators which
+typically combine multiple individual devices. These properties are used to
+configure a single device. For example, ConfigureBreakoutBoard's
+<xref:OpenEphys.Onix1.ConfigureBreakoutBoard.AnalogIO> properties configure the
+Breakout Board's Analog I/O device.
diff --git a/articles/getting-started/onix-configuration.md b/articles/getting-started/onix-configuration.md
@@ -38,19 +38,11 @@ element](xref:data-elements) named <xref:OpenEphys.Onix1.ContextTask>.
 
 Hardware configuration is performed when `ContextTask` passes through a [configuration
 operator](xref:configure). A configuration operator allows the user to configure hardware by editing
-its properties. There are two types of configuration operators: [device configuration
-operators](xref:device-configure) and [device group configuration operators](xref:configure).
+its properties. There are two types of configuration operators: [Device configuration
+operators](xref:device-configure) and [Device Group configuration operators](xref:configure).
 Device configuration operators allow configuration of a single device contained by a headstage,
-miniscope, or breakout board whereas device group configuration operators allow configuration of all
+miniscope, or breakout board whereas Device Group configuration operators allow configuration of all
 devices contained by a headstage, miniscope, or breakout board.
-<!--We recommend using device group configuration operators for concision and
-ease-of-use, though device operators can be helpful in more advanced workflows that require writing
-to hardware while the workflow is running.
-
-Any number of configuration operators can be chained following a CreateContext operator. If you use
-only device group configuration operators, you'll have between one and three total
-configuration operators: one for the breakout board and one for each port that is connected to a
-headstage or miniscope.  -->
 
 ::: workflow
 ![/workflows/getting-started/configure.bonsai workflow](../../workflows/getting-started/configure.bonsai)
@@ -64,8 +56,6 @@ related to data acquisition such as ReadSize and WriteSize. Setting the ReadSize
 particular workflow is a balancing act of minimizing latency of data data transfers from the ONIX
 system and avoiding data accumulation in the ONIX system's hardware buffer.
 
-<!-- TODO: Need a separate tutorial or guide on this -->
-
 ::: workflow
 ![/workflows/getting-started/start-acquisition.bonsai workflow](../../workflows/getting-started/start-acquisition.bonsai)
 :::
diff --git a/images/properties-pane.webp b/images/properties-pane.webp
diff --git a/img-src/properties-pane.png b/img-src/properties-pane.png
diff --git a/img-src/properties-pane.svg b/img-src/properties-pane.svg
diff --git a/template/ManagedReference.extension.js b/template/ManagedReference.extension.js
@@ -13,6 +13,7 @@ function extractEnumData(model) {
     .map(child => ({
       'field&value': child.syntax.content[0].value,
       'description': [child.summary, child.remarks].join(''),
+      'id': child.uid.replaceAll('.', '_'),
     }));
 }
 
@@ -40,7 +41,8 @@ function processChildProperty(child, sharedModel) {
       'enum': enumFields,
     },
     'configuration': configuration,
-    'acquisition': acquisition
+    'acquisition': acquisition,
+    'id': child.uid.replaceAll('.', '_'),
   }
 }
 
@@ -80,6 +82,7 @@ function extractConstituentOperatorsData(model) {
         'constituentOperator': true,
         'hasProperties': properties === undefined || properties.length === 0 ? false : true,
         'properties': properties,
+        'id': child.uid.replaceAll('.', '_'),
       };
     }
   );
@@ -121,7 +124,7 @@ exports.preTransform = function (model) {
     if (operator.hub) {
       properties = extractConstituentOperatorsData(model);
       properties.unshift({
-        'object': 'Configuration',
+        'object': model.name[0].value.replace('Configure', ''),
         'constituentOperator': false,
         'hasProperties': true,
         'properties': sortPropertiesData([
diff --git a/template/ManagedReference.overwrite.js b/template/ManagedReference.overwrite.js
@@ -1,5 +1,10 @@
+var common = require('./ManagedReference.common.js');
+
 exports.getOptions = function (model) {
+    var ignoreChildrenBookmarks = model._splitReference && model.type && common.getCategory(model.type) === 'ns';
+    
     return {
-        isShared: true
+        isShared: true,
+        bookmarks: common.getBookmarks(model, ignoreChildrenBookmarks)
     };
 }
diff --git a/template/partials/class.tmpl.partial b/template/partials/class.tmpl.partial
@@ -2,13 +2,13 @@
   <div class="Important alert alert-info">
     <h5>TIP</h5>
     <p>
-      This is a device configuration operator. <a class="xref" href="configure.html">Aggregate configuration operators</a> are recommended in lieu of <a class="xref" href="device-configure.html">device configuration operators</a> for interfacing with Open Ephys Onix hardware.
+      This is a <a class="xref" href="device-configure.html">Device configuration operator</a>. <a class="xref" href="configure.html">Device Group configuration operators</a> are recommended instead of Device configuration operators for interfacing with Open Ephys Onix hardware.
     </p>
   </div>
 {{/oe.operator.configureDevice}}
 
 <div>
-  <h1 id="{{id}}" data-uid="{{oe.uid}}" class="text-break" style="display: inline-block;">
+  <h1 class="text-break" style="display: inline-block;">
     {{oe.name}}
     {{#sourceurl}}<a class="header-action link-secondary" title="View source" href="{{sourceurl}}"><i class="bi bi-code-slash"></i></a>{{/sourceurl}}
   </h1>
@@ -31,41 +31,33 @@
 
 {{#oe.operator.hub}}
 
-<h3>Configuration</h3>
-
 {{#oe.properties}}
-{{^constituentOperator}}
 
-<p>These are properties of the aggregate operator:</p>
+<h3 class="text-break" style="display: inline-block;" id="{{{id}}}">{{{object}}}</h3> 
 
-{{#hasProperties}}
-{{>partials/propertyTable}}
-{{/hasProperties}}
-{{^hasProperties}}
-<p>This operator does not have any configuration options.</p>
-{{/hasProperties}}
+{{^constituentOperator}}
+<a class="xref" href="~/api/OpenEphys.Onix1.html#device-group">
+  <button class="badge oe-badge-border oe-badge-green">Device Group</button>
+</a>
+<p>These are properties of the {{{oe.name}}} <a class="xref" href="~/api/configure.html">Device Group configuration operator</a>:</p>
 {{/constituentOperator}}
-{{/oe.properties}}
 
-<h3>Devices</h3>
-
-{{#oe.properties}}
 {{#constituentOperator}}
-
-<h4>{{{object}}}</h4>
-
-<p>{{{object}}} is a {{{type}}} operator encapsulated by the {{oe.name}} operator with the following properties:</p>
+<a class="xref" href="~/api/OpenEphys.Onix1.html#device">
+  <button class="badge oe-badge-border oe-badge-purple">Device</button>
+</a>
+<p>{{{object}}} is a {{{type}}} device operator contained by the {{{oe.name}}} operator with the following properties:</p>
+{{/constituentOperator}}
 
 {{#hasProperties}}
 {{>partials/propertyTable}}
 {{/hasProperties}}
-
 {{^hasProperties}}
-<p>This operator does not have any configuration options.</p>
+<p>This operator does not have any properties to set.</p>
 {{/hasProperties}}
 
-{{/constituentOperator}}
 {{/oe.properties}}
+
 {{/oe.operator.hub}}
 
 {{#oe}}
diff --git a/template/partials/enum.tmpl.partial b/template/partials/enum.tmpl.partial
@@ -15,7 +15,7 @@
   {{#oe.enum}}
   <tr>
     <td style="white-space: no-wrap">
-        <code>
+        <code id={{{id}}}>
           {{{field&value}}}
         </code>
       </td>
diff --git a/template/partials/hardware/configuration.tmpl.partial b/template/partials/hardware/configuration.tmpl.partial
@@ -5,7 +5,7 @@
   in Bonsai. This process comprises of the following steps: 
   <ul>
     <li> 
-      Create an ONIX acquisition context using <Sa class="xref"
+      Create an ONIX acquisition context using <a class="xref"
       href="~/api/OpenEphys.Onix1.CreateContext.html">CreateContext</a>
     </li>
     <li> 
diff --git a/template/partials/propertyTable.tmpl.partial b/template/partials/propertyTable.tmpl.partial
@@ -9,21 +9,21 @@
   {{#properties}}
   <tr>
     <td style = "white-space: nowrap;">
-      <code>{{{name}}}</code>
+      <code id="{{{id}}}">{{{name}}}</code>
       {{#acquisition}}
       <div>
         <a class="xref" href="~/api/OpenEphys.Onix1.html#acquisition">
-          <button class="badge bg-primary-subtle border border-primary-subtle text-primary-emphasis rounded-pill">
-            acquisition
+          <button class="badge oe-badge-border oe-badge-blue">
+            Acquisition
           </button>
         </a>
       </div>
       {{/acquisition}}
       {{#configuration}}
       <div>
         <a class="xref" href="~/api/OpenEphys.Onix1.html#configuration">
-          <button class="badge bg-warning-subtle border border-warning-subtle text-warning-emphasis rounded-pill">
-            configuration 
+          <button class="badge oe-badge-border oe-badge-yellow">
+            Configuration 
           </button>
         </a>
       </div>
@@ -39,7 +39,7 @@
       <table>
         {{#enum}}
         <tr>
-          <td class="term"><code>{{{field&value}}}</code></td>
+          <td class="term" id="{{{id}}}"><code>{{{field&value}}}</code></td>
           <td class="description">{{{enumDescription}}}</td>
         </tr>
         {{/enum}}
diff --git a/template/public/main.css b/template/public/main.css
