Import docs

.github/workflows/pages.yaml

@@ -1,15 +1,12 @@
-# Sample workflow for building and deploying a Hugo site to GitHub Pages
-name: Deploy Hugo site to Pages
+name: Deploy site to Pages
 
 on:
-  # Runs on pushes targeting the default branch
   push:
     branches: ["main"]
 
-  # Allows you to run this workflow manually from the Actions tab
+  # Allows manual dispatch
   workflow_dispatch:
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: read
   pages: write
@@ -38,26 +35,34 @@ jobs:
         with:
           fetch-depth: 0  # fetch all history for .GitInfo and .Lastmod
           submodules: recursive
+
+      - name: Install system prerequisites
+        run: sudo apt-get install -yq
+             python3
+             git
+
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
           go-version: '1.22'
+
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v4
+
       - name: Setup Hugo
         run: |
           wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
           && sudo dpkg -i ${{ runner.temp }}/hugo.deb
-      - name: Build with Hugo
+
+      - name: Build
         env:
           # For maximum backward compatibility with Hugo modules
           HUGO_ENVIRONMENT: production
           HUGO_ENV: production
         run: |
-          hugo \
-            --gc --minify \
-            --baseURL "${{ steps.pages.outputs.base_url }}/"
+          python3 build.py publish --base-url="${{ steps.pages.outputs.base_url }}/"
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:

.gitignore

@@ -2,3 +2,8 @@
 public/
 resources/
 .hugo_build.lock
+
+# Imported data
+_temp/
+static/images/modules-src/
+content/docs/pysy_mlink_api_embed.fragment

assets/css/custom.css

@@ -0,0 +1,25 @@
+
+.align-right {
+  text-align: right;
+  float: right;
+  margin-left: 2px;
+}
+
+.docutils.literal {
+  overflow-wrap: break-word;
+  border-radius: 0.375rem;
+  border-width: 1px;
+  border-color: rgb(0 0 0 / var(--tw-border-opacity));
+  --tw-border-opacity: 0.04;
+  background-color: rgb(0 0 0 / var(--tw-bg-opacity));
+  --tw-bg-opacity: 0.03;
+  padding-top: 0.125rem;
+  padding-bottom: 0.125rem;
+  padding-left: .25em;
+  padding-right: .25em;
+  font-size: .9em;
+
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+  font-feature-settings: normal;
+  font-variation-settings: normal;
+}

build.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+#
+# Copyright (C) 2023-2024 Matthias Klumpp <matthias@tenstral.net>
+#
+# SPDX-License-Identifier: LGPL-3.0+
+
+
+import os
+import sys
+import shutil
+import subprocess
+from argparse import ArgumentParser
+from glob import glob
+
+
+SYNTALOS_GIT_URL = 'https://github.com/syntalos/syntalos.git'
+
+
+class SyWebBuilder:
+    """Helper to build the Syntalos website."""
+
+    def __init__(self, root_dir):
+        self._root_dir = root_dir
+
+    def _copy_images(self, src, dst):
+        for root, _, files in os.walk(src):
+            for fname in files:
+                if fname.endswith(('.png', '.svg')):
+                    src_file_path = os.path.join(root, fname)
+                    relative_path = os.path.relpath(root, src)
+                    dst_dir_path = os.path.join(dst, relative_path)
+
+                    if not os.path.exists(dst_dir_path):
+                        os.makedirs(dst_dir_path)
+
+                    dst_file_path = os.path.join(dst_dir_path, fname)
+                    self._copy_file(src_file_path, dst_file_path)
+
+    def _copy_file(self, src, dst):
+        shutil.copy2(src, dst)
+
+        src_short = src.replace(self._root_dir, '')
+        dst_short = dst.replace(self._root_dir, '')
+        print(f"Copied {src_short} to {dst_short}")
+
+    def _prepare(self) -> bool:
+        """Prepare website."""
+        sysrc_dir = os.path.join(self._root_dir, '_temp', 'syntalos-src')
+        if os.path.exists(sysrc_dir):
+            subprocess.check_call(['git', '-C', sysrc_dir, 'pull'])
+        else:
+            subprocess.check_call(['git', 'clone', '--depth=1', SYNTALOS_GIT_URL, sysrc_dir])
+
+        # copy module icons & graphics
+        self._copy_images(
+            os.path.join(sysrc_dir, 'modules'),
+            os.path.join(self._root_dir, 'static', 'images', 'modules-src'),
+        )
+        self._copy_images(
+            os.path.join(sysrc_dir, 'data', 'modules'),
+            os.path.join(self._root_dir, 'static', 'images', 'modules-src'),
+        )
+
+        # copy prebuilt HTML Python docs
+        self._copy_file(
+            os.path.join(sysrc_dir, 'docs', 'pysy_mlink_api_embed.html'),
+            os.path.join(self._root_dir, 'content', 'docs', 'pysy_mlink_api_embed.fragment'),
+        )
+
+        return True
+
+    def serve(self) -> bool:
+        """Build the Syntalos website and display it."""
+
+        if not self._prepare():
+            return False
+
+        subprocess.check_call(['hugo', 'serve'])
+
+        return True
+
+    def publish(self, base_url=None) -> bool:
+        """Build the Syntalos website and display it."""
+
+        if not self._prepare():
+            return False
+
+        cmd = ['hugo', '--gc', '--minify']
+        if base_url:
+            cmd.extend(['--baseURL', base_url])
+
+        subprocess.check_call(cmd)
+
+        return True
+
+
+def run(script_dir):
+
+    parser = ArgumentParser(description='Build the Syntalos documentation & website.')
+    parser.add_argument('command', choices=['serve', 'publish'], help='Command to execute.')
+    parser.add_argument('--base-url', default=None, help='Base URL for the publish command.')
+
+    args = parser.parse_args()
+
+    builder = SyWebBuilder(script_dir)
+    if args.command == 'serve':
+        if not builder.serve():
+            return 1
+    elif args.command == 'publish':
+        if not builder.publish(args.base_url):
+            return 1
+    else:
+        print('No command set! Use either "serve" or "publish".')
+        return 4
+
+    return 0
+
+
+if __name__ == '__main__':
+    thisfile = os.path.realpath(__file__)
+    if not os.path.isabs(thisfile):
+        thisfile = os.path.normpath(os.path.join(os.getcwd(), thisfile))
+    thisdir = os.path.normpath(os.path.join(os.path.dirname(thisfile)))
+    os.chdir(thisdir)
+
+    sys.exit(run(thisdir))

content/_index.md

@@ -3,7 +3,21 @@ title: Syntalos
 toc: false
 ---
 
-This is the landing page.
+
+![Syntalos Screenshot](images/screenshots/v0.8.4-ui-overview.png)
+
+Syntalos is a software for timestamp-synchronized parallel data acquisition from diverse data sources,
+such as cameras, microendoscopes, Intan electrophysiology amplifiers or Firmata-based serial interfaces.
+The software also allows user-defined closed-loop interventions via its built-in Python scripting support.
+It is specifically designed for use in (neuro)scientific in vivo behavior experiments.
+
+These pages document the software, for users who just want to use Syntalos, as well as developers who want
+to make more advanced changes.
+
+<script async defer src="https://buttons.github.io/buttons.js"></script>
+<a class="github-button" href="https://github.com/bothlab/syntalos" data-icon="octicon-star" data-size="large" data-show-count="true" aria-label="Star bothlab/syntalos on GitHub">Star</a>
+<a class="github-button" href="https://github.com/bothlab/syntalos/releases" data-icon="octicon-download" data-size="large" aria-label="Download bothlab/syntalos on GitHub">Download</a>
+
 
 ## Explore
 

content/docs/_index.md

@@ -1,18 +1,14 @@
 ---
 title: Documentation
-next: first-page
+next: docs/intro
 ---
 
-This is a demo of the theme's documentation layout.
+Welcome to the Syntalos documentation!
 
-## Hello, World!
+## Explore
 
-```go {filename="main.go"}
-package main
-
-import "fmt"
-
-func main() {
-    fmt.Println("Hello, World!")
-}
-```
+{{< cards >}}
+  {{< card link="setup/install/" title="Install Syntalos" icon="download" >}}
+  {{< card link="intro/" title="Introduction" icon="newspaper" >}}
+  {{< card link="modules/" title="Modules" icon="view-grid" >}}
+{{< /cards >}}

content/docs/intro.md

@@ -0,0 +1,34 @@
+---
+title: Introduction
+next: docs/setup/install
+---
+
+Acquisition of data from a variety of heterogeneous sources with precisely aligned timestamps is a requirement for many
+kinds of in vivo experiments.
+In addition, it is often necessary to manipulate experimental settings based on the animal's state or behavior,
+and to store acquired data in a standardized format to simplify subsequent analysis.
+To address these requirements, Syntalos exists.
+It is capable of simultaneous acquisition of data from an arbitrary amount of sources,
+including multi-channel electrophysiological recordings and different
+types of live imaging devices.
+
+At the same time, the program supports closed-loop, real-time interventions with
+different actuators. Precisely matching timestamps for all inputs are ensured by continuous statistical analysis
+and correction of the individual devices' timestamps and by use of the parallel-processing capabilities of
+modern CPUs. New data sources can be integrated relatively easily as well, using Syntalos' module system.
+
+All data generated from a given experiment is stored in a well-defined, comprehensive structure,
+making it easy to compare, pool or share data between experimentalists with different research questions.
+With these features, Syntalos enables reliable multi-modal recordings as well as closed-loop interventions
+for many different (neuro)scientific questions.
+
+Design Goals
+------------
+
+`Coming soon!`
+
+
+Architecture Overview
+---------------------
+
+`Coming soon!`

content/docs/modules/_index.md

@@ -0,0 +1,42 @@
+---
+title: Modules
+type: docs
+prev: docs/intro
+sidebar:
+  open: true
+---
+
+The Syntalos Module Index contains basic information about Syntalos modules,
+their usage instructions and programming interface information.
+
+
+## Modules
+
+{{< modtoc directory="docs/modules" >}}
+
+
+## Common Stream Metadata
+
+Some metadata is always available on output streams:
+
+<table class="list-table" width="100%">
+  <thead>
+    <tr>
+      <th style="width: 15%;">Direction</th>
+      <th style="width: 85%;">Metadata</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Out🠺</td>
+      <td>
+        <ul>
+          <li><code>src_mod_type</code>: String, type (unique name) of the source module.</li>
+          <li><code>src_mod_name</code>: String, name (user-defined) of the source module.</li>
+          <li><code>src_mod_port_title</code>: String, title of the source module's port.</li>
+          <li><code>data_name_proposal</code>: String, proposed name for data storage of data generated by source module.</li>
+        </ul>
+      </td>
+    </tr>
+  </tbody>
+</table>

content/docs/modules/audiosource.rst

@@ -0,0 +1,45 @@
+---
+title: Audio Source
+---
+.. image:: /images/modules-src/audiosource/audiosource.svg
+   :width: 80
+   :align: right
+
+The "Audio Source" module can generate various test sounds, from sine-waves to clicks.
+
+Usage
+=====
+
+Configure as usual. Configuration can not be changed after experiment has started.
+
+
+Ports
+=====
+
+.. list-table::
+   :widths: 14 10 22 54
+   :header-rows: 1
+
+   * - Name
+     - Direction
+     - Data Type
+     - Description
+
+   * - 🠺Control
+     - In
+     - ``ControlCommand``
+     - Supports ``START``, ``STOP``/``PAUSE`` commands to start/stop the audio output.
+
+
+Stream Metadata
+===============
+
+.. list-table::
+   :widths: 15 85
+   :header-rows: 1
+
+   * - Name
+     - Metadata
+
+   * - 🠺Control
+     - None