Merge pull request #6 from harp-tech/modern-theme

Update to DocFX modern theme

Author: glopesdev

.gitmodules

@@ -34,3 +34,4 @@
 [submodule "protocol"]
 	path = protocol
 	url = https://github.com/harp-tech/protocol.git
+	branch = doc-generation

articles/about.md

@@ -1,11 +1,15 @@
+---
+uid: about
+---
+
 # What is Harp
 
-Harp describes a communication protocol and architecture, as well as specific devices that implement these structures.
+[!include[what-is-harp](./what-is-harp.md)]
 
 ## Why Harp was developed
 
-Current Neuroscience experiments rely on multiple parallel streams of data, acquired from different devices, to examine how neural circuit activity relates to animal behaviours. This requires precise timestamping of experimental events, so that neural and behavioural data can be accurately ordered in time. Temporally aligning different streams of data, often acquired at different frequencies, rapidly becomes more difficult as setups increase in complexity.
+Time is a critical variable in systems neuroscience experiments. As setups increase in complexity, temporally aligning multiple datastreams acquired from different devices rapidly becomes more difficult. Exploring how neural circuit activity relates to animal behaviour requires precise timestamping of experimental events, so that neural and behavioural data can be accurately ordered in time.
 
-Harp is a family of high-performance devices that make it easy for scientists to synchronize and extend the functionality of their setups. Harp devices can configure, control, & track a wide range of peripheral devices such as cameras, LEDs, nosepokes, & motors. Connecting an extra Harp device is a straightforward way to add extra functionality to a setup. All Harp devices can be connected to a shared clock line, self-synchronizing to a precision of tens of microseconds. This means that all experimental events are timestamped on the same clock and no post-hoc alignment of timing is necessary.
+Harp is being developed as a cross-institutional collaboration to develop an ecosystem of high-performance devices that make it easy for scientists to synchronize and extend the functionality of their setups. Harp devices should be able to configure, control, and track a wide range of peripheral devices such as cameras, LEDs, nosepokes, and motors. Connecting an extra Harp device to add functionality to a setup should be straightforward and place no extra burden on researchers.
 
-From an engineering perspective, extending the functionality of a setup can also be difficult, if this requires developing a new device, including how this device will communicates with a computer, and how users will interact with the device. By agreeing beforehand how the entire family of devices will communicate, engineers do not have to reinvent or attune protocols each time they wish to develop a new device. This leads to faster, cheaper, and more robust development.
+From an engineering perspective, we also want to accelerate the development process of extending the functionality of a setup, and make it easier to develop new devices, deciding how these devices communicate a computer, and how researchers interact with the device. By agreeing beforehand how the entire ecosystem works together, from signal acquisition to analysis, we can support engineers not having to reinvent or attune protocols each time they wish to develop a new device. This leads to faster, cheaper, and more robust development of scientific tools.

articles/intro.md

@@ -16,6 +16,6 @@ The latest release of the Bonsai.Harp can be downloaded and installed through th
 
 A high-level interface will usually be available for the specific Harp device you are using. To install them, first change the package manager **Package source** to `nuget.org`. Then, in the search bar, look for your device by typing: `harp.<device>`. For instance, for the Harp Behavior board, you should find the following package:
 
-![HarpDevicePackage](~/images/behaviorpackage.png)
+![HarpDevicePackage](~/images/behavior-package.png)
 
 The device nodes should now be available in the Bonsai Toolbox. You can now start using them in your workflows.

articles/what-is-harp.md

@@ -0,0 +1,9 @@
+Harp is a standard for asynchronous real-time data acquisition and experimental control in neuroscience. It includes specifications for a lightweight and versatile binary communication protocol, a set of common registers for microcontroller firmware, and a clock synchronization protocol.
+
+:::wrap-right
+![Behavior Peripherals](~/images/behavior-peripherals.jpg)
+:::
+
+Commands and events processed by all Harp devices are hardware timestamped and streamed back to the host computer over USB with a one millisecond latency. The stateless and symmetric communication protocol allows temporally accurate logging while avoiding the need for fixed sampling rates and redundant processing. Harp devices can be connected to a shared clock line and continuously self-synchronise their clocks to a precision of tens of microseconds. This means that all experimental events are timestamped on the same clock and no post-hoc alignment of timing is necessary.
+
+The Harp ecosystem currently includes devices to configure, control, and collect data from a wide range of peripheral devices such as cameras, LEDs, nosepokes, and motors. Combining Harp devices is an easy way to extend experimental setup functionality with integrated timestamp synchronisation across devices.

docfx.json

@@ -16,6 +16,7 @@
       ],
       "dest": "api",
       "filter": "filter.yml",
+      "enumSortOrder": "declaringOrder",
       "disableGitFeatures": false,
       "disableDefaultFilter": false
     }
@@ -72,6 +73,8 @@
     ],
     "globalMetadata": {
       "_enableNewTab": true,
+      "_enableSearch": true,
+      "_appFooter": "<span>&copy; 2023 harp-tech and Contributors</span> - <span>Licensed under <a href=\"https://creativecommons.org/licenses/by-sa/4.0/\">CC BY-SA 4.0</a>.</span> - <span>Made with <a href=\"https://dotnet.github.io/docfx\">docfx</a></span>",
       "_gitContribute": {
         "repo": "https://github.com/harp-tech/docs",
         "branch": "main",
@@ -83,7 +86,8 @@
     "fileMetadataFiles": [],
     "template": [
       "default",
-      "templates/html"
+      "modern",
+      "template"
     ],
     "postProcessors": [ "ExtractSearchIndex" ],
     "markdownEngineName": "markdig",
@@ -97,7 +101,6 @@
     "keepFileLink": false,
     "cleanupCacheHistory": false,
     "disableGitFeatures": false,
-    "xrefService": [ "https://learn.microsoft.com/api/xref/query?uid={uid}" ],
     "xref": [
       "https://bonsai-rx.org/docs/xrefmap.yml",
       "https://horizongir.github.io/opencv.net/xrefmap.yml",

images/behaviorpackage.png images/behavior-package.pngimages/behaviorpackage.png renamed to images/behavior-package.png

@@ -1,6 +1,12 @@
 # **Harp** Documentation
 
-Harp is a family of devices that configure, control, and collect data from a wide range of peripheral devices such as cameras, LEDs, nosepokes, and motors. Combining Harp devices is an easy way to extend experimental setup functionality with integrated timestamp synchronisation across devices.
+[!include[what-is-harp](./articles/what-is-harp.md)]
+
+## Quick Start
+
+* [What is Harp](./articles/about.md)
+* [Binary Protocol](./protocol/BinaryProtocol-8bit.md)
+* [Bonsai Interface](./articles/intro.md)
 
 > [!Warning]
 > These docs are under active development, feel free to contribute by either [raising an issue](https://github.com/harp-tech/docs/issues) or following the links saying **Improve this Doc**.

images/behavior-peripherals.jpg

@@ -0,0 +1,34 @@
+.workflow {
+  border: 1px solid #e3e3e3;
+  padding: 1px;
+}
+
+.workflow > p > img {
+  padding-top: 12px;
+  padding-left: 12px;
+  padding-right: 12px;
+}
+
+.codeHeader {
+  box-sizing: content-box;
+  background-color: #f2f2f2;
+  color: #171717;
+  display: flex;
+  flex-direction: row;
+  border: 1px solid #e3e3e3;
+  border-bottom: 0;
+  margin-top: 16px;
+  min-height: 30px;
+}
+
+.codeHeader > .language {
+  padding: 2px 16px;
+  flex-grow: 1;
+  line-height: 26px;
+}
+
+.wrap-right > p > img,
+.wrap-right > p > a > img {
+  max-width: 50%;
+  float: inline-end;
+}