From b4dc71f5798c80ca8692409cd3e529c5a6fcf156 Mon Sep 17 00:00:00 2001 From: cjsha Date: Tue, 29 Oct 2024 18:37:48 -0400 Subject: [PATCH 1/4] Organize TOC - Dataframes have a dropdown - enums have a drop - remove excess operators from datai/o dropdown --- template/partials/class.tmpl.partial | 9 +- template/toc.extension.js | 156 +++++++++++++++------------ 2 files changed, 89 insertions(+), 76 deletions(-) diff --git a/template/partials/class.tmpl.partial b/template/partials/class.tmpl.partial index 2f36cd4..965d8c7 100644 --- a/template/partials/class.tmpl.partial +++ b/template/partials/class.tmpl.partial @@ -1,11 +1,8 @@ {{#oe.operator.configureDevice}} -
-
Caution
+
+
TIP

- This is a device configuration operator. Device configuration operators are not recommended for interfacing with off-the-shelf ONIX hardware. Use aggregate configuration operators to do that instead. -

-

- To understand the benefits of aggregate configuration operators, refer to the device configuration operators page. + This is a device configuration operator. Aggregate configuration operators are recommended in lieu of device configuration operators for interfacing with Open Ephys Onix hardware.

{{/oe.operator.configureDevice}} diff --git a/template/toc.extension.js b/template/toc.extension.js index 018d4b6..b990c36 100644 --- a/template/toc.extension.js +++ b/template/toc.extension.js @@ -8,84 +8,100 @@ exports.preTransform = function (model) { if (model.items[0].name === 'OpenEphys.Onix1'){ if (model.items[0].items){ itemsItemsLength = model.items[0].items.length; - let items = [{ - 'name': 'Core Operators', - 'href' : 'core.html', - 'topicHref': 'core.html', - 'topicUid': 'core', - 'items': []}, { - 'name': 'Configuration Operators', - 'href' : 'configure.html', - 'topicHref': 'configure.html', - 'topicUid': 'configure', - 'items': []}, { - 'name': 'Data I/O Operators', - 'href' : 'dataio.html', - 'topicHref': 'dataio.html', - 'topicUid': 'dataio', - 'items': []}, { - 'name': 'Other', - 'items': [ + let items = [ + { + 'name': 'Core Operators', + 'href' : 'core.html', + 'topicHref': 'core.html', + 'topicUid': 'core', + 'items': [] + }, + { + 'name': 'Configuration Operators', + 'href' : 'configure.html', + 'topicHref': 'configure.html', + 'topicUid': 'configure', + 'items': [] + }, + { + 'name': 'Data I/O Operators', + 'href' : 'dataio.html', + 'topicHref': 'dataio.html', + 'topicUid': 'dataio', + 'items': [] + }, + { + 'name': 'Device Configuration Operators', + 'href' : 'device-configure.html', + 'topicHref': 'device-configure.html', + 'topicUid': 'device-configure', + 'items': [] + }, + { + 'name': 'Data Frames', + 'href' : 'dataframes.html', + 'topicHref': 'dataframes.html', + 'topicUid': 'dataframes', + 'items': [] + }, + { + 'name': 'Other', + 'href' : 'other.html', + 'topicHref': 'other.html', + 'topicUid': 'other', + 'items': + [ + { + 'name': 'Enums', + 'href' : 'enums.html', + 'topicHref': 'enums.html', + 'topicUid': 'enums', + 'items': [] + } + ] + } + ]; + for (let i = 0; i < itemsItemsLength; i++) + { + globalYml = '~/api/' + model.items[0].items[i].topicUid + '.yml'; + globalModel = model.__global._shared[globalYml]; + if (globalModel?.type === 'class' || globalModel?.type === 'struct') + { + if (model.items[0].items[i].name.includes('CreateContext') || model.items[0].items[i].name.includes('StartAcquisition')) { - 'name': 'Device Configuration Operators', - 'href' : 'device-configure.html', - 'topicHref': 'device-configure.html', - 'topicUid': 'device-configure', - 'items': [], + items[0].items.push(model.items[0].items[i]); } - ] - }]; - for (let i = 0; i < itemsItemsLength; i++) { - globalYml = '~/api/' + model.items[0].items[i].topicUid + '.yml'; - if (model.items[0].items[i].name.includes('Frame') || - model.items[0].items[i].name.includes('DeviceFactory') || - model.items[0].items[i].name.includes('ContextTask') || - model.items[0].items[i].name.includes('DeviceNameConverter') || - model.items[0].items[i].name.includes('ConfigureDS90UB9x') || - model.items[0].items[i].name.includes('ConfigureFmcLinkController') || - model.items[0].items[i].name.includes('DeviceContext') || - model.items[0].items[i].name.includes('NeuropixelsV2QuadShankElectrode') || - model.items[0].items[i].name.includes('NeuropixelsV2QuadShankProbeConfiguration') || - model.items[0].items[i].name.includes('NeuropixelsV1eAdc')){ - model.items[0].items[i].hide = true; - } - else if (model.__global._shared[globalYml] && model.__global._shared[globalYml].type === 'enum') { - model.items[0].items[i].hide = true; - } - else { - if (model.__global._shared[globalYml] && model.__global._shared[globalYml].type === 'class'){ - const inheritanceLength = model.__global._shared[globalYml].inheritance.length; - device = false; - hub = false; - for (let j = 0; j < inheritanceLength; j++){ - if (model.__global._shared[globalYml].inheritance[j].uid === 'OpenEphys.Onix1.SingleDeviceFactory'){ - device = true; - } - else if (model.__global._shared[globalYml].inheritance[j].uid === 'OpenEphys.Onix1.MultiDeviceFactory'){ - hub = true; - } - } - if (model.items[0].items[i].name.includes('CreateContext') || model.items[0].items[i].name.includes('StartAcquisition')){ - items[0].items.push(model.items[0].items[i]); - } - else if (device){ - items[3].items[0].items.push(model.items[0].items[i]); - } - else if (hub){ - items[1].items.push(model.items[0].items[i]); - } - else { - items[2].items.push(model.items[0].items[i]); - } + else if (globalModel?.inheritance.some(inherited => inherited.uid === 'OpenEphys.Onix1.MultiDeviceFactory')) + { + items[1].items.push(model.items[0].items[i]); } + else if (globalModel?.inheritance.some(inherited => inherited.uid === 'OpenEphys.Onix1.SingleDeviceFactory')) + { + items[3].items.push(model.items[0].items[i]); + } + else if ((globalModel.syntax?.content[0].value.includes('ElementCategory.Source') || + globalModel.syntax?.content[0].value.includes('ElementCategory.Sink') || + globalModel?.inheritance.some(inherited => inherited.uid.includes('Bonsai.Source')) || + globalModel?.inheritance.some(inherited => inherited.uid.includes('Bonsai.Sink'))) && + !globalModel.syntax?.content[0].value.includes('abstract')) + { + items[2].items.push(model.items[0].items[i]); + } + else if (model.items[0].items[i].name.includes('ContextTask') || + model.items[0].items[i].name.includes('OutputClockParameters') || + globalModel?.inheritance.some(inherited => inherited.uid === 'OpenEphys.Onix1.DataFrame' || inherited.uid === 'OpenEphys.Onix1.BufferedDataFrame')) + { + items[4].items.push(model.items[0].items[i]); + } + } + else if (globalModel && globalModel.type === 'enum') + { + items[5].items[0].items.push(model.items[0].items[i]); } } model.items[0].items = items; } } - // if (model.items[1].name === 'OpenEphys.Onix1.Design'){ - // model.items.splice(1, 1); - // } return model; } From 9dcd1aeadc02df1e1b818bbd0f0c873e07f858f3 Mon Sep 17 00:00:00 2001 From: cjsha Date: Tue, 29 Oct 2024 19:04:09 -0400 Subject: [PATCH 2/4] Fix broken references --- api/dataframes.md | 9 +++++++++ api/enums.md | 7 +++++++ template/toc.extension.js | 2 -- 3 files changed, 16 insertions(+), 2 deletions(-) create mode 100644 api/dataframes.md create mode 100644 api/enums.md diff --git a/api/dataframes.md b/api/dataframes.md new file mode 100644 index 0000000..e06f62f --- /dev/null +++ b/api/dataframes.md @@ -0,0 +1,9 @@ +--- +uid: dataframes +title: Data Frames +--- + +Dataframes are units of data produced by Onix1 . + +Although is not technically a data +frame, it is contained in this class. \ No newline at end of file diff --git a/api/enums.md b/api/enums.md new file mode 100644 index 0000000..595acc9 --- /dev/null +++ b/api/enums.md @@ -0,0 +1,7 @@ +--- +uid: enums +title: Enums +--- + +Enumerators (enums for short) assign names to numbers. They are used extensively throughout the OpenEphysOnix1 Bonsai package. + diff --git a/template/toc.extension.js b/template/toc.extension.js index b990c36..d45acf4 100644 --- a/template/toc.extension.js +++ b/template/toc.extension.js @@ -46,8 +46,6 @@ exports.preTransform = function (model) { }, { 'name': 'Other', - 'href' : 'other.html', - 'topicHref': 'other.html', 'topicUid': 'other', 'items': [ From 08c60de39e1ac9152d6949cb44ab3da23baf3e3f Mon Sep 17 00:00:00 2001 From: cjsha Date: Wed, 30 Oct 2024 15:16:19 -0400 Subject: [PATCH 3/4] Address review feedback - Add content to OpenEphys.Onix1 page --- api/constants.md | 6 ++++ api/data-elements.md | 6 ++++ api/dataframes.md | 9 ----- api/device-configure.md | 2 +- api/enums.md | 7 ---- api/overview.md | 9 +++++ docfx.json | 37 ++++++--------------- template/ManagedReference.html.primary.tmpl | 12 ++++++- template/toc.extension.js | 36 ++++++++++---------- 9 files changed, 61 insertions(+), 63 deletions(-) create mode 100644 api/constants.md create mode 100644 api/data-elements.md delete mode 100644 api/dataframes.md delete mode 100644 api/enums.md create mode 100644 api/overview.md diff --git a/api/constants.md b/api/constants.md new file mode 100644 index 0000000..58bae11 --- /dev/null +++ b/api/constants.md @@ -0,0 +1,6 @@ +--- +uid: constants +title: Constants +--- + +These constants are used throughout the Bonsai package to assign names to numbered values. \ No newline at end of file diff --git a/api/data-elements.md b/api/data-elements.md new file mode 100644 index 0000000..aa64334 --- /dev/null +++ b/api/data-elements.md @@ -0,0 +1,6 @@ +--- +uid: data-elements +title: Data Elements +--- + +Data elements are produced by Bonsai operators. \ No newline at end of file diff --git a/api/dataframes.md b/api/dataframes.md deleted file mode 100644 index e06f62f..0000000 --- a/api/dataframes.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -uid: dataframes -title: Data Frames ---- - -Dataframes are units of data produced by Onix1 . - -Although is not technically a data -frame, it is contained in this class. \ No newline at end of file diff --git a/api/device-configure.md b/api/device-configure.md index 2aa2bf3..9e138c3 100644 --- a/api/device-configure.md +++ b/api/device-configure.md @@ -3,7 +3,7 @@ uid: device-configure title: Device Configuration Operators --- -> [!IMPORTANT] +> [!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. diff --git a/api/enums.md b/api/enums.md deleted file mode 100644 index 595acc9..0000000 --- a/api/enums.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -uid: enums -title: Enums ---- - -Enumerators (enums for short) assign names to numbers. They are used extensively throughout the OpenEphysOnix1 Bonsai package. - diff --git a/api/overview.md b/api/overview.md new file mode 100644 index 0000000..df8a8d6 --- /dev/null +++ b/api/overview.md @@ -0,0 +1,9 @@ +--- +uid: OpenEphys.Onix1 +title: OpenEphys.Onix1 +--- + +OpenEphys.Onix1 is a Bonsai package containing interfaces for data acquisition and control of ONIX hardware. This section +of the docs is dedicated to facilitate construction of workflows using the OpenEphys.Onix1 package. + +In Bonsai, press F1 while an OpenEphys.Onix1 node is selected in the workflow editor to quickly open this reference. \ No newline at end of file diff --git a/docfx.json b/docfx.json index 5eeb847..7ba3fd3 100644 --- a/docfx.json +++ b/docfx.json @@ -3,9 +3,7 @@ { "src": [ { - "files": [ - "src/**.csproj" - ] + "files": ["src/**.csproj"] } ], "dest": "api", @@ -19,35 +17,20 @@ "index.md": "landing" } }, - "content": [ - "articles/**.{md,yml}", - "api/**.{md,yml}", - "toc.yml", - "index.md" - ], - "resource": [ - "logo.svg", - "favicon.png", - "images/**", - "workflows/**" + "content": [ + { + "files": ["articles/**.{md,yml}", "api/**.{md,yml}", "toc.yml", "index.md"], + "exclude": ["api/overview.md"] + } ], + "resource": ["logo.svg", "favicon.png", "images/**", "workflows/**"], "output": "_site", "overwrite": [ { - "files": [ - ], - "exclude": [ - "obj/**", - "_site/**" - ] + "files": ["api/overview.md"] } ], - "template": [ - "default", - "modern", - "template", - "docfx-tools/template" - ], + "template": ["default", "modern", "template", "docfx-tools/template"], "globalMetadata": { "_enableNewTab": true, "_enableSearch": true, @@ -77,4 +60,4 @@ "rules": { "InvalidBookmark": "suggestion" } -} \ No newline at end of file +} diff --git a/template/ManagedReference.html.primary.tmpl b/template/ManagedReference.html.primary.tmpl index 6c8209b..e76a192 100644 --- a/template/ManagedReference.html.primary.tmpl +++ b/template/ManagedReference.html.primary.tmpl @@ -8,4 +8,14 @@ {{#isEnum}} {{>partials/enum}} -{{/isEnum}} \ No newline at end of file +{{/isEnum}} + +{{#isNamespace}} +
+

+ {{{title}}} + +

+
+ {{{conceptual}}} +{{/isNamespace}} \ No newline at end of file diff --git a/template/toc.extension.js b/template/toc.extension.js index d45acf4..d4cbfa6 100644 --- a/template/toc.extension.js +++ b/template/toc.extension.js @@ -31,17 +31,10 @@ exports.preTransform = function (model) { 'items': [] }, { - 'name': 'Device Configuration Operators', - 'href' : 'device-configure.html', - 'topicHref': 'device-configure.html', - 'topicUid': 'device-configure', - 'items': [] - }, - { - 'name': 'Data Frames', - 'href' : 'dataframes.html', - 'topicHref': 'dataframes.html', - 'topicUid': 'dataframes', + 'name': 'Data Elements', + 'href' : 'data-elements.html', + 'topicHref': 'data-elements.html', + 'topicUid': 'data-elements', 'items': [] }, { @@ -50,10 +43,17 @@ exports.preTransform = function (model) { 'items': [ { - 'name': 'Enums', - 'href' : 'enums.html', - 'topicHref': 'enums.html', - 'topicUid': 'enums', + 'name': 'Device Configuration Operators', + 'href' : 'device-configure.html', + 'topicHref': 'device-configure.html', + 'topicUid': 'device-configure', + 'items': [] + }, + { + 'name': 'Constants', + 'href' : 'constants.html', + 'topicHref': 'constants.html', + 'topicUid': 'constants', 'items': [] } ] @@ -75,7 +75,7 @@ exports.preTransform = function (model) { } else if (globalModel?.inheritance.some(inherited => inherited.uid === 'OpenEphys.Onix1.SingleDeviceFactory')) { - items[3].items.push(model.items[0].items[i]); + items[4].items[0].items.push(model.items[0].items[i]); } else if ((globalModel.syntax?.content[0].value.includes('ElementCategory.Source') || globalModel.syntax?.content[0].value.includes('ElementCategory.Sink') || @@ -89,12 +89,12 @@ exports.preTransform = function (model) { model.items[0].items[i].name.includes('OutputClockParameters') || globalModel?.inheritance.some(inherited => inherited.uid === 'OpenEphys.Onix1.DataFrame' || inherited.uid === 'OpenEphys.Onix1.BufferedDataFrame')) { - items[4].items.push(model.items[0].items[i]); + items[3].items.push(model.items[0].items[i]); } } else if (globalModel && globalModel.type === 'enum') { - items[5].items[0].items.push(model.items[0].items[i]); + items[4].items[1].items.push(model.items[0].items[i]); } } model.items[0].items = items; From 425db7c60e2d8b781bff4db8b549d42ce4c22156 Mon Sep 17 00:00:00 2001 From: cjsha Date: Thu, 31 Oct 2024 10:34:46 -0400 Subject: [PATCH 4/4] Address bparks feedback in review --- api/configure.md | 5 ++++- api/overview.md | 2 +- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/api/configure.md b/api/configure.md index 1ec4f22..57f20ff 100644 --- a/api/configure.md +++ b/api/configure.md @@ -3,4 +3,7 @@ uid: configure title: Configuration Operators --- -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. \ No newline at end of file +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.. \ No newline at end of file diff --git a/api/overview.md b/api/overview.md index df8a8d6..caa291c 100644 --- a/api/overview.md +++ b/api/overview.md @@ -3,7 +3,7 @@ uid: OpenEphys.Onix1 title: OpenEphys.Onix1 --- -OpenEphys.Onix1 is a Bonsai package containing interfaces for data acquisition and control of ONIX hardware. This section +`OpenEphys.Onix1` is a Bonsai package containing interfaces for data acquisition and control of ONIX hardware. This section of the docs is dedicated to facilitate construction of workflows using the OpenEphys.Onix1 package. In Bonsai, press F1 while an OpenEphys.Onix1 node is selected in the workflow editor to quickly open this reference. \ No newline at end of file