start fleshing out documentation sections

astro.config.mjs

@@ -24,8 +24,32 @@ export default defineConfig({
           autogenerate: { directory: 'run' },
         },
         {
-          label: 'Reference',
+          label: 'Concepts',
-          autogenerate: { directory: 'reference' },
+          autogenerate: { directory: 'concepts' },
+        },
+        {
+          label: 'Modules',
+          items: [
+            {
+              label: "Generator",
+              collapsed: true,
+              autogenerate: { directory: 'modules/generator' }
+            },
+            {
+              label: "Network",
+              collapsed: true,
+              autogenerate: { directory: 'modules/network' }
+            },
+            {
+              label: "Misc",
+              collapsed: true,
+              autogenerate: { directory: 'modules/misc' }
+            },
+          ]
+        },
+        {
+          label: 'Examples',
+          autogenerate: { directory: 'examples' },
         },
       ],
     }),

src/content/docs/concepts/config.md

@@ -1,7 +1,7 @@
 ---
 title: Config
 sidebar:
-  order: 2
+    order: 1
 ---
 The showbridge router's config is entirely controlled by a YAML/JSON config file. This file must be made by hand for now. I do provide some starter/example configs to look at to get a general idea of what one entails. 
 

src/content/docs/concepts/modules.md

@@ -0,0 +1,14 @@
+---
+title: Modules
+sidebar:
+    order: 2
+---
+
+Modules are anything that can produce input and/or handle output. They are configured in the `modules` property of the [router config file](/reference/config).
+
+## YAML Definition
+A module YAML block has the following properties
+
+- **id**: user assigned unique identifier that will be used to reference a module instance in a [route](/reference/routes)
+- **type**: the module type
+- **params**: optional map for module configuration values. The valid values will depend on the module type

src/content/docs/concepts/processors.md

@@ -0,0 +1,13 @@
+---
+title: Processors
+sidebar:
+    order: 4
+---
+
+Processors are anything that create or manipulate messages. They are configured in the `processors` property of an individual [route](/reference/routes). Processors have the ability to change the type of the message flowing through the system so a byte array can come into a `osc.message.decode` processor and a OSC message type will come out of the processor.
+
+## YAML Definition
+A processor YAML block has the following properties
+
+- **type**: the processor type
+- **params**: optional map for processor configuration values. The valid values will depend on the processor type

src/content/docs/concepts/routes.md

@@ -0,0 +1,14 @@
+---
+title: Routes
+sidebar:
+    order: 3
+---
+
+Routes take the messages coming from a module and push them out another module. The message can be optionally "processed" with any number of processor steps.
+
+## YAML Definition
+- **input**: the id of the [module](/reference/modules) that will provide messages to this route
+- **processors**: (optional) array of [processors](/reference/processors) that will be called in order and the result of the previous will be fed to the next processor.
+  - if at any point the output of a processor is `null` the entire route will be terminated (subject to change to support output `null` values?)
+  - an error in a processor step will also result in the route being terminated
+- **output**: the id of the [module](/reference/modules) that will consume messages from the route

src/content/docs/examples/http-to-osc.md

@@ -0,0 +1,27 @@
+---
+title: HTTP > OSC
+---
+
+This config starts an HTTP server listening on port `3000`. Any HTTP request coming into that server will result in a OSC message being sent to `127.0.0.1:8000` with the address set to the path from the incoming HTTP message.
+
+```
+# config.yaml
+modules:
+  - id: http
+    type: net.http.server
+    params:
+      port: 3000
+  - id: udp
+    type: net.udp.client
+    params:
+      host: 127.0.0.1
+      port: 8000
+routes:
+  - input: http
+    processors:
+      - type: osc.message.create    # create OSC message
+        params:
+          address: "{{.URL.Path}}"  # template the address from the incoming message
+      - type: osc.message.encode    # turn OSC message into bytes
+    output: udp
+```

src/content/docs/modules/generator/interval.md

@@ -0,0 +1,19 @@
+---
+title: Interval
+sidebar:
+    order: 2
+---
+The interval module emits a message at a specified duration
+
+- **type**: `gen.interval`
+- **params**:
+    - **duration**: time in milliseconds between messsages
+
+### Example snippet
+Emits a message every 3 seconds
+```
+- id: every3Secs
+  type: gen.interval
+    params:
+      duration: 3000
+```

src/content/docs/modules/generator/timer.md

@@ -0,0 +1,19 @@
+---
+title: Timer
+sidebar:
+    order: 1
+---
+The timer module emits only one message after a specified duration
+
+- **type**: `gen.timer`
+- **params**:
+    - **duration**: time in milliseconds to wait before emitting message
+
+### Example snippet
+Emits a message 5 seconds after the module is initialized
+```
+- id: 5secs
+  type: gen.timer
+    params:
+      duration: 5000
+```

src/content/docs/modules/network/http-client.md

@@ -0,0 +1,15 @@
+---
+title: HTTP Client
+sidebar:
+    order: 1
+---
+The HTTP Client module emits a message contianing the response of the HTTP calls it makes.
+
+- **type**: `net.http.client`
+- **params**: no params are needed for HTTP client
+
+### Example
+```
+- id: httpSender1
+  type: net.http.client
+```

src/content/docs/modules/network/http-server.md

@@ -0,0 +1,19 @@
+---
+title: HTTP Server
+sidebar:
+    order: 2
+---
+The HTTP server module emits a message for every HTTP request that is made to the server
+
+- **type**: `net.http.server`
+- **params**:
+    - **port**: TCP port to listen for HTTP requests on
+
+### Example
+Start an HTTP server listening on port 3000
+```
+- id: httpServer
+  type: net.http.server
+  params:
+    port: 3000
+```

src/content/docs/modules/network/tcp-client.md

@@ -0,0 +1,27 @@
+---
+title: TCP Client
+sidebar:
+    order: 3
+---
+The TCP client module connects to TCP server and emits a message for every message it receives from the server that it connects to. Messages are determined by "framing" techniques as TCP is a stream based protocol. The module will attempt to reconnect anytime the connection is closed.
+
+- **type**: `net.tcp.client`
+- **params**:
+    - **host**: IP or FQDN to connect to
+    - **port**: TCP port to connect to
+    - **framing**: how to chunk the TCP stream into "messages"
+        - LF `\n`
+        - CR `\r`
+        - CRLF `\r\n`
+        - [SLIP](https://en.wikipedia.org/wiki/Serial_Line_Internet_Protocol)
+
+### Example
+Open a TCP connection to `127.0.0.1` port 8888, any incoming data will be split on line-feed (`\n`)
+```
+- id: tcpClient
+  type: net.tcp.client
+  params:
+    host: 127.0.0.1
+    port: 8888
+    framing: LF
+```

src/content/docs/modules/network/tcp-server.md

@@ -0,0 +1,27 @@
+---
+title: TCP Server
+sidebar:
+    order: 4
+---
+The TCP server module emits a message for every message it receives from clients that connect to it. Messages are determined by "framing" techniques as TCP is a stream based protocol.
+
+- **type**: `net.tcp.server`
+- **params**:
+    - **ip**: (optional) IP address to bind the TCP server to, if left out it will listen on all interfaces
+    - **port**: TCP port to listen on
+    - **framing**: how to chunk of the incoming TCP stream into "messages"
+        - LF `\n`
+        - CR `\r`
+        - CRLF `\r\n`
+        - [SLIP](https://en.wikipedia.org/wiki/Serial_Line_Internet_Protocol)
+
+### Example
+Start a TCP server listening on port 8888, incoming data will be split on line-feed (`\n`)
+```
+- id: tcpServer
+  type: net.tcp.server
+  params:
+    ip: 127.0.0.1
+    port: 8888
+    framing: LF
+```

src/content/docs/modules/network/udp-client.md

@@ -0,0 +1,21 @@
+---
+title: UDP Client
+sidebar:
+    order: 5
+---
+The UDP client module sends messages to a the configured `host` and `port`. This module does not receive any message and so using it as an `input` to a [route](/concepts/routes) would be pointless.
+
+- **type**: `net.udp.client`
+- **params**:
+    - **host**: IP or FQDN to send message to
+    - **port**: UDP port to send messages to
+
+### Example
+setup up a UDP client that will send UDP packets to `127.0.0.1` on port 8888
+```
+- id: udpClient
+  type: net.udp.client
+  params:
+    host: 127.0.0.1
+    port: 8888
+```

src/content/docs/modules/network/udp-server.md

@@ -0,0 +1,21 @@
+---
+title: UDP Server
+sidebar:
+    order: 6
+---
+The UDP server module emits a message for every incoming UDP datagram.
+
+- **type**: `net.udp.server`
+- **params**:
+    - **ip**: (optional) IP address to bind the UDP server to, if left out it will listen on all interfaces
+    - **port**: UDP port to listen on
+
+### Example
+Start a UDP server listening on port 8888 and only on `127.0.0.1`
+```
+- id: udpServer
+  type: net.udp.server
+  params:
+    ip: 127.0.0.1
+    port: 8888
+```

src/content/docs/reference/modules.md

@@ -1,5 +0,0 @@
----
-title: Modules
-sidebar:
-  order: 3
----

src/content/docs/reference/processors.md

@@ -1,5 +0,0 @@
----
-title: Processors
-sidebar:
-  order: 5
----

src/content/docs/reference/routes.md

@@ -1,5 +0,0 @@
----
-title: Routes
-sidebar:
-  order: 4
----

src/content/docs/showbridge/dictionary.md

@@ -1,10 +1,8 @@
 ---
 title: Dictionary
-sidebar:
-  order: 1
 ---
 
 - **router**: throughout documentation I will use the term router to refer to configured/running instance of showbridge
 - **modules**: modules are configured instances that can produce or consume message like a TCP server or a UDP client
 - **routes**: routes take messages coming from a module (input), do some optional processing and send that message to a module (output)
-- **processors**: processors process messages, the processors are localized to the route the processor is a part of. Examples of processors or turning bytes into an OSC message or parsing a string into an integer 
+- **processors**: processors process messages, the processors are localized to the route the processor is a part of. Examples of processors or turning bytes into an OSC message or parsing a string into an integer