Add documentation for the pub-sub pattern

docs/articles/intro.md

@@ -0,0 +1,9 @@
+# Introduction
+
+Bonsai.ZeroMQ is a [Bonsai](https://bonsai-rx.org/) interface for [ZeroMQ](https://zeromq.org/) providing a flexible networking and messaging library for coordinating distributed processing. The core patterns discussed in the [ØMQ Guide](https://zguide.zeromq.org/) are exposed via reactive operators and discussed in detail in the [Patterns](patterns.md) chapter.
+
+You can use Bonsai.ZeroMQ to transmit requests and data across different workflows running in the same computer, or in a different computer. You can also use the package to create endpoints for interfacing Bonsai with other languages supporting ZeroMQ.
+
+## Installing the package
+
+To install Bonsai.ZeroMQ use the Bonsai package manager and search for the **Bonsai - ZeroMQ** package.

docs/articles/patterns.md

@@ -0,0 +1,9 @@
+# Patterns
+
+ZeroMQ provides a set of [sockets and patterns](https://zguide.zeromq.org/docs/chapter2/) for building distributed systems. We have adapted these patterns to fit neatly into the Bonsai visual language by defining a set of reactive operators named after each socket type.
+
+| Pattern | Description | Sockets |
+| ------- | ----------- | ------- |
+| [Publish-Subscribe](pub-sub.md) | One to many data distribution | <xref href="Bonsai.ZeroMQ.Publisher"/>, <xref href="Bonsai.ZeroMQ.Subscriber"/> |
+
+Each section in this chapter describes a basic ZeroMQ messaging pattern, usually involving complementary pairs of sockets, and provides examples of use that you can copy and paste directly into the editor. Most examples make use of the [OSC](xref:Bonsai.Osc) package for formatting and parsing binary-coded messages for numeric data, or the <xref href="Bonsai.Vision.EncodeImage"/> and <xref href="Bonsai.Vision.DecodeImage"/> operators for serializing video data.

docs/articles/pub-sub.md

@@ -0,0 +1,29 @@
+---
+uid: pub-sub
+title: "Publish-Subscribe"
+---
+
+# Publish-Subscribe
+
+The publish-subscribe (pub-sub) pattern implements one-way data distribution, in which a <xref href="Bonsai.ZeroMQ.Publisher"/> node pushes a stream of updates to a set of <xref href="Bonsai.ZeroMQ.Subscriber"/> nodes. Messages pushed by the publisher are sent to all subscribers active at the moment of sending the message.
+
+```mermaid
+graph LR
+    A(Publisher) ---|PUB| B(<p></p>)
+    B -->|SUB| D(Subscriber)
+    B -->|SUB| E(Subscriber)
+    B -->|SUB| F(Subscriber)
+```
+
+Distribution is fully asynchronous, and publisher and subscriber nodes can be started in any order. Publisher nodes may specify a <xref href="Bonsai.ZeroMQ.Publisher.Topic"/> for each sent message. When connecting to a publisher, subscriber nodes can subscribe to one or more topics. If no topic is specified, subscriber nodes will receive all messages from the publisher.
+
+> [!Warning]
+> Subscriber nodes are not guaranteed to receive the same number of messages sent by the publisher or by other subscribers. Initializing a connection to the publisher can take long enough that messages already being sent are lost, so it is best to assume that pub-sub streams are infinite streams with no beginning or end.
+
+### **Example:** Simple publish-subscribe stream
+
+In the example below, a periodic timer publishes counter updates with multiple downstream subscribers. The numeric data is packed into an array of bytes for transmission, and parsed back on reception.
+
+:::workflow
+![Pub-Sub workflow](~/workflows/pub-sub.bonsai)
+:::

docs/articles/toc.yml

@@ -0,0 +1,12 @@
+- name: Getting Started
+  href: intro.md
+  items:
+    - name: Quickstart
+      href: intro.md
+- name: Patterns
+  href: patterns.md
+  items:
+    - name: Overview
+      href: patterns.md
+    - name: Publish-Subscribe
+      href: pub-sub.md

docs/docfx.json

@@ -79,6 +79,9 @@
     "cleanupCacheHistory": false,
     "disableGitFeatures": false,
     "xrefService": [ "https://xref.docs.microsoft.com/query?uid={uid}" ],
-    "xref": [ "https://bonsai-rx.org/docs/xrefmap.yml" ]
+    "xref": [
+      "https://bonsai-rx.org/docs/xrefmap.yml",
+      "https://horizongir.github.io/reactive/xrefmap.yml"
+    ]
   }
 }

docs/workflows/pub-sub.bonsai

@@ -49,36 +49,6 @@
       <Expression xsi:type="osc:Parse">
         <osc:TypeTag>h</osc:TypeTag>
       </Expression>
-      <Expression xsi:type="Combinator">
-        <Combinator xsi:type="rx:Timer">
-          <rx:DueTime>PT0S</rx:DueTime>
-          <rx:Period>PT0.5S</rx:Period>
-        </Combinator>
-      </Expression>
-      <Expression xsi:type="osc:Format">
-        <osc:Address>/</osc:Address>
-      </Expression>
-      <Expression xsi:type="MemberSelector">
-        <Selector>Buffer.Array</Selector>
-      </Expression>
-      <Expression xsi:type="Combinator">
-        <Combinator xsi:type="zmq:Publisher">
-          <zmq:ConnectionString>tcp://localhost:5558</zmq:ConnectionString>
-          <zmq:Topic>data2</zmq:Topic>
-        </Combinator>
-      </Expression>
-      <Expression xsi:type="Combinator">
-        <Combinator xsi:type="zmq:Subscriber">
-          <zmq:ConnectionString>tcp://localhost:5558</zmq:ConnectionString>
-          <zmq:Topic />
-        </Combinator>
-      </Expression>
-      <Expression xsi:type="MemberSelector">
-        <Selector>Last.Buffer</Selector>
-      </Expression>
-      <Expression xsi:type="osc:Parse">
-        <osc:TypeTag>h</osc:TypeTag>
-      </Expression>
     </Nodes>
     <Edges>
       <Edge From="0" To="1" Label="Source1" />
@@ -88,11 +58,6 @@
       <Edge From="5" To="6" Label="Source1" />
       <Edge From="7" To="8" Label="Source1" />
       <Edge From="8" To="9" Label="Source1" />
-      <Edge From="10" To="11" Label="Source1" />
-      <Edge From="11" To="12" Label="Source1" />
-      <Edge From="12" To="13" Label="Source1" />
-      <Edge From="14" To="15" Label="Source1" />
-      <Edge From="15" To="16" Label="Source1" />
     </Edges>
   </Workflow>
 </WorkflowBuilder>

src/Bonsai.ZeroMQ/Publisher.cs

@@ -10,6 +10,7 @@ namespace Bonsai.ZeroMQ
     /// Represents an operator that creates a publisher socket for transmitting a
     /// sequence of messages as part of the pub-sub pattern.
     /// </summary>
+    /// <seealso cref="Subscriber"/>
     [Description("Creates a publisher socket for transmitting a sequence of messages as part of the pub-sub pattern.")]
     public class Publisher : Sink<NetMQMessage>
     {

src/Bonsai.ZeroMQ/Subscriber.cs

@@ -11,6 +11,7 @@ namespace Bonsai.ZeroMQ
     /// Represents an operator that creates a subscriber socket for receiving a sequence
     /// of messages as part of the pub-sub pattern.
     /// </summary>
+    /// <seealso cref="Publisher"/>
     [Description("Creates a subscriber socket for receiving a sequence of messages as part of the pub-sub pattern.")]
     public class Subscriber : Source<NetMQMessage>
     {