Skip to content

Commit c231091

Browse files
ximionximion
committed
Import docs
1 parent 3aea386 commit c231091

File tree

74 files changed

+2887
-27
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

74 files changed

+2887
-27
lines changed

‎.github/workflows/pages.yaml

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,12 @@
1-
# Sample workflow for building and deploying a Hugo site to GitHub Pages
2-
name: Deploy Hugo site to Pages
1+
name: Deploy site to Pages
32

43
on:
5-
# Runs on pushes targeting the default branch
64
push:
75
branches: ["main"]
86

9-
# Allows you to run this workflow manually from the Actions tab
7+
# Allows manual dispatch
108
workflow_dispatch:
119

12-
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
1310
permissions:
1411
contents: read
1512
pages: write
@@ -38,26 +35,35 @@ jobs:
3835
with:
3936
fetch-depth: 0 # fetch all history for .GitInfo and .Lastmod
4037
submodules: recursive
38+
39+
- name: Install system prerequisites
40+
run: sudo apt-get install -yq
41+
python3
42+
python3-docutils
43+
git
44+
4145
- name: Setup Go
4246
uses: actions/setup-go@v5
4347
with:
4448
go-version: '1.22'
49+
4550
- name: Setup Pages
4651
id: pages
4752
uses: actions/configure-pages@v4
53+
4854
- name: Setup Hugo
4955
run: |
5056
wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
5157
&& sudo dpkg -i ${{ runner.temp }}/hugo.deb
52-
- name: Build with Hugo
58+
59+
- name: Build
5360
env:
5461
# For maximum backward compatibility with Hugo modules
5562
HUGO_ENVIRONMENT: production
5663
HUGO_ENV: production
5764
run: |
58-
hugo \
59-
--gc --minify \
60-
--baseURL "${{ steps.pages.outputs.base_url }}/"
65+
python3 build.py publish --base-url="${{ steps.pages.outputs.base_url }}/"
66+
6167
- name: Upload artifact
6268
uses: actions/upload-pages-artifact@v3
6369
with:

‎.gitignore

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,8 @@
22
public/
33
resources/
44
.hugo_build.lock
5+
6+
# Imported data
7+
_temp/
8+
static/images/modules-src/
9+
content/docs/pysy_mlink_api_embed.fragment

‎assets/css/custom.css

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
2+
.align-right {
3+
text-align: right;
4+
float: right;
5+
margin-left: 2px;
6+
}
7+
8+
.docutils.literal {
9+
overflow-wrap: break-word;
10+
border-radius: 0.375rem;
11+
border-width: 1px;
12+
border-color: rgb(0 0 0 / var(--tw-border-opacity));
13+
--tw-border-opacity: 0.04;
14+
background-color: rgb(0 0 0 / var(--tw-bg-opacity));
15+
--tw-bg-opacity: 0.03;
16+
padding-top: 0.125rem;
17+
padding-bottom: 0.125rem;
18+
padding-left: .25em;
19+
padding-right: .25em;
20+
font-size: .9em;
21+
22+
font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
23+
font-feature-settings: normal;
24+
font-variation-settings: normal;
25+
}

‎build.py

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
#!/usr/bin/env python3
2+
#
3+
# Copyright (C) 2023-2024 Matthias Klumpp <matthias@tenstral.net>
4+
#
5+
# SPDX-License-Identifier: LGPL-3.0+
6+
7+
8+
import os
9+
import sys
10+
import shutil
11+
import subprocess
12+
from argparse import ArgumentParser
13+
from glob import glob
14+
15+
16+
SYNTALOS_GIT_URL = 'https://github.com/syntalos/syntalos.git'
17+
18+
19+
class SyWebBuilder:
20+
"""Helper to build the Syntalos website."""
21+
22+
def __init__(self, root_dir):
23+
self._root_dir = root_dir
24+
25+
def _copy_images(self, src, dst):
26+
for root, _, files in os.walk(src):
27+
for fname in files:
28+
if fname.endswith(('.png', '.svg')):
29+
src_file_path = os.path.join(root, fname)
30+
relative_path = os.path.relpath(root, src)
31+
dst_dir_path = os.path.join(dst, relative_path)
32+
33+
if not os.path.exists(dst_dir_path):
34+
os.makedirs(dst_dir_path)
35+
36+
dst_file_path = os.path.join(dst_dir_path, fname)
37+
self._copy_file(src_file_path, dst_file_path)
38+
39+
def _copy_file(self, src, dst):
40+
shutil.copy2(src, dst)
41+
42+
src_short = src.replace(self._root_dir, '')
43+
dst_short = dst.replace(self._root_dir, '')
44+
print(f"Copied {src_short} to {dst_short}")
45+
46+
def _prepare(self) -> bool:
47+
"""Prepare website."""
48+
49+
if not shutil.which('rst2html'):
50+
raise RuntimeError('The `rst2html` executable is missing. Install it to continue.')
51+
52+
sysrc_dir = os.path.join(self._root_dir, '_temp', 'syntalos-src')
53+
if os.path.exists(sysrc_dir):
54+
subprocess.check_call(['git', '-C', sysrc_dir, 'pull'])
55+
else:
56+
subprocess.check_call(['git', 'clone', '--depth=1', SYNTALOS_GIT_URL, sysrc_dir])
57+
58+
# copy module icons & graphics
59+
self._copy_images(
60+
os.path.join(sysrc_dir, 'modules'),
61+
os.path.join(self._root_dir, 'static', 'images', 'modules-src'),
62+
)
63+
self._copy_images(
64+
os.path.join(sysrc_dir, 'data', 'modules'),
65+
os.path.join(self._root_dir, 'static', 'images', 'modules-src'),
66+
)
67+
68+
# copy prebuilt HTML Python docs
69+
self._copy_file(
70+
os.path.join(sysrc_dir, 'docs', 'pysy_mlink_api_embed.html'),
71+
os.path.join(self._root_dir, 'content', 'docs', 'pysy_mlink_api_embed.fragment'),
72+
)
73+
74+
return True
75+
76+
def serve(self) -> bool:
77+
"""Build the Syntalos website and display it."""
78+
79+
if not self._prepare():
80+
return False
81+
82+
subprocess.check_call(['hugo', 'serve'])
83+
84+
return True
85+
86+
def publish(self, base_url=None) -> bool:
87+
"""Build the Syntalos website and display it."""
88+
89+
if not self._prepare():
90+
return False
91+
92+
cmd = ['hugo', '--gc', '--minify']
93+
if base_url:
94+
cmd.extend(['--baseURL', base_url])
95+
96+
subprocess.check_call(cmd)
97+
98+
return True
99+
100+
101+
def run(script_dir):
102+
103+
parser = ArgumentParser(description='Build the Syntalos documentation & website.')
104+
parser.add_argument('command', choices=['serve', 'publish'], help='Command to execute.')
105+
parser.add_argument('--base-url', default=None, help='Base URL for the publish command.')
106+
107+
args = parser.parse_args()
108+
109+
builder = SyWebBuilder(script_dir)
110+
if args.command == 'serve':
111+
if not builder.serve():
112+
return 1
113+
elif args.command == 'publish':
114+
if not builder.publish(args.base_url):
115+
return 1
116+
else:
117+
print('No command set! Use either "serve" or "publish".')
118+
return 4
119+
120+
return 0
121+
122+
123+
if __name__ == '__main__':
124+
thisfile = os.path.realpath(__file__)
125+
if not os.path.isabs(thisfile):
126+
thisfile = os.path.normpath(os.path.join(os.getcwd(), thisfile))
127+
thisdir = os.path.normpath(os.path.join(os.path.dirname(thisfile)))
128+
os.chdir(thisdir)
129+
130+
sys.exit(run(thisdir))

‎content/_index.md

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,21 @@ title: Syntalos
33
toc: false
44
---
55

6-
This is the landing page.
6+
7+
![Syntalos Screenshot](images/screenshots/v0.8.4-ui-overview.png)
8+
9+
Syntalos is a software for timestamp-synchronized parallel data acquisition from diverse data sources,
10+
such as cameras, microendoscopes, Intan electrophysiology amplifiers or Firmata-based serial interfaces.
11+
The software also allows user-defined closed-loop interventions via its built-in Python scripting support.
12+
It is specifically designed for use in (neuro)scientific in vivo behavior experiments.
13+
14+
These pages document the software, for users who just want to use Syntalos, as well as developers who want
15+
to make more advanced changes.
16+
17+
<script async defer src="https://buttons.github.io/buttons.js"></script>
18+
<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>
19+
<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>
20+
721

822
## Explore
923

‎content/docs/_index.md

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,14 @@
11
---
22
title: Documentation
3-
next: first-page
3+
next: docs/intro
44
---
55

6-
This is a demo of the theme's documentation layout.
6+
Welcome to the Syntalos documentation!
77

8-
## Hello, World!
8+
## Explore
99

10-
```go {filename="main.go"}
11-
package main
12-
13-
import "fmt"
14-
15-
func main() {
16-
fmt.Println("Hello, World!")
17-
}
18-
```
10+
{{< cards >}}
11+
{{< card link="setup/install/" title="Install Syntalos" icon="download" >}}
12+
{{< card link="intro/" title="Introduction" icon="newspaper" >}}
13+
{{< card link="modules/" title="Modules" icon="view-grid" >}}
14+
{{< /cards >}}

‎content/docs/intro.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: Introduction
3+
next: docs/setup/install
4+
---
5+
6+
Acquisition of data from a variety of heterogeneous sources with precisely aligned timestamps is a requirement for many
7+
kinds of in vivo experiments.
8+
In addition, it is often necessary to manipulate experimental settings based on the animal's state or behavior,
9+
and to store acquired data in a standardized format to simplify subsequent analysis.
10+
To address these requirements, Syntalos exists.
11+
It is capable of simultaneous acquisition of data from an arbitrary amount of sources,
12+
including multi-channel electrophysiological recordings and different
13+
types of live imaging devices.
14+
15+
At the same time, the program supports closed-loop, real-time interventions with
16+
different actuators. Precisely matching timestamps for all inputs are ensured by continuous statistical analysis
17+
and correction of the individual devices' timestamps and by use of the parallel-processing capabilities of
18+
modern CPUs. New data sources can be integrated relatively easily as well, using Syntalos' module system.
19+
20+
All data generated from a given experiment is stored in a well-defined, comprehensive structure,
21+
making it easy to compare, pool or share data between experimentalists with different research questions.
22+
With these features, Syntalos enables reliable multi-modal recordings as well as closed-loop interventions
23+
for many different (neuro)scientific questions.
24+
25+
Design Goals
26+
------------
27+
28+
`Coming soon!`
29+
30+
31+
Architecture Overview
32+
---------------------
33+
34+
`Coming soon!`

‎content/docs/modules/_index.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: Modules
3+
type: docs
4+
prev: docs/intro
5+
sidebar:
6+
open: true
7+
---
8+
9+
The Syntalos Module Index contains basic information about Syntalos modules,
10+
their usage instructions and programming interface information.
11+
12+
13+
## Modules
14+
15+
{{< modtoc directory="docs/modules" >}}
16+
17+
18+
## Common Stream Metadata
19+
20+
Some metadata is always available on output streams:
21+
22+
<table class="list-table" width="100%">
23+
<thead>
24+
<tr>
25+
<th style="width: 15%;">Direction</th>
26+
<th style="width: 85%;">Metadata</th>
27+
</tr>
28+
</thead>
29+
<tbody>
30+
<tr>
31+
<td>Out🠺</td>
32+
<td>
33+
<ul>
34+
<li><code>src_mod_type</code>: String, type (unique name) of the source module.</li>
35+
<li><code>src_mod_name</code>: String, name (user-defined) of the source module.</li>
36+
<li><code>src_mod_port_title</code>: String, title of the source module's port.</li>
37+
<li><code>data_name_proposal</code>: String, proposed name for data storage of data generated by source module.</li>
38+
</ul>
39+
</td>
40+
</tr>
41+
</tbody>
42+
</table>

‎content/docs/modules/audiosource.rst

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: Audio Source
3+
---
4+
.. image:: /images/modules-src/audiosource/audiosource.svg
5+
:width: 80
6+
:align: right
7+
8+
The "Audio Source" module can generate various test sounds, from sine-waves to clicks.
9+
10+
Usage
11+
=====
12+
13+
Configure as usual. Configuration can not be changed after experiment has started.
14+
15+
16+
Ports
17+
=====
18+
19+
.. list-table::
20+
:widths: 14 10 22 54
21+
:header-rows: 1
22+
23+
* - Name
24+
- Direction
25+
- Data Type
26+
- Description
27+
28+
* - 🠺Control
29+
- In
30+
- ``ControlCommand``
31+
- Supports ``START``, ``STOP``/``PAUSE`` commands to start/stop the audio output.
32+
33+
34+
Stream Metadata
35+
===============
36+
37+
.. list-table::
38+
:widths: 15 85
39+
:header-rows: 1
40+
41+
* - Name
42+
- Metadata
43+
44+
* - 🠺Control
45+
- None

0 commit comments

Comments
 (0)