404 2.0 documentation (#410)

* Init docs with some index files and nav setup

* Scaffold docs

* Indices, installation, usage

* Nice things

* Adding a manipulator

* Added home cards

* Better cards and grammar

* Colors and icons

* Setup for docstring (won't do yet)

* Add build scripts, remove type checking

* Install Python in build

* Use separate environment without install

.github/workflows/autoformat-and-lint.yml

@@ -38,5 +38,5 @@ jobs:
       - name: 🧶 Lint
         run: hatch fmt --check
 
-      - name: 🔍 Type Check
-        run: hatch -e types run check
+#      - name: 🔍 Type Check
+#        run: hatch -e types run check

.github/workflows/build-docs.yml

@@ -0,0 +1,36 @@
+name: Build Documentation
+
+on:
+  pull_request:
+    branches: [ "main" ]
+  workflow_dispatch:
+  workflow_call:
+
+jobs:
+  build:
+    name: Build
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: 🛎 Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+
+      - name: 🐍 Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: "pip"
+
+      - name: 📦 Install Hatch
+        uses: pypa/hatch@install
+
+      - name: 🔨 Build Documentation
+        run: hatch -e docs run build
+
+      - name: ⬆️ Upload Artifacts
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: "site"

.github/workflows/deploy-docs.yml

@@ -0,0 +1,41 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [ "main" ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "deploy-docs"
+  cancel-in-progress: true
+
+jobs:
+
+  build:
+    name: Build
+    uses: ./.github/workflows/build-docs.yml
+
+  deploy:
+    name: Deploy Documentation
+
+    needs: build
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+
+    steps:
+
+      - name: 🎛 Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: 🚀 Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -8,20 +8,22 @@
 
 <!-- [![Build](https://github.com/VirtualBrainLab/ephys-link/actions/workflows/build.yml/badge.svg)](https://github.com/VirtualBrainLab/ephys-link/actions/workflows/build.yml) -->
 
-<img width="100%" src="https://github.com/VirtualBrainLab/ephys-link/assets/82800265/0c7c60b1-0926-4697-a461-221554f82de1" alt="Manipulator and probe in pinpoint moving in sync">
-
 The [Electrophysiology Manipulator Link](https://github.com/VirtualBrainLab/ephys-link)
 (or Ephys Link for short) is a Python [Socket.IO](https://socket.io/docs/v4/#what-socketio-is) server that allows any
 Socket.IO-compliant application (such
 as [Pinpoint](https://github.com/VirtualBrainLab/Pinpoint))
 to communicate with manipulators used in electrophysiology experiments.
 
+<img width="100%" src="https://github.com/VirtualBrainLab/ephys-link/assets/82800265/0c7c60b1-0926-4697-a461-221554f82de1" alt="Manipulator and probe in pinpoint moving in sync">
+
 **Supported Manipulators:**
 
-| Manufacturer | Model                                                                   |
-|--------------|-------------------------------------------------------------------------|
-| Sensapex     | <ul> <li>uMp-4</li> <li>uMp-3</li> </ul>                                |
-| New Scale    | <ul> <li>Pathfinder MPM Control v2.8+</li> <li>M3-USB-3:1-EP</li> </ul> |
+| Manufacturer | Model                                                   |
+|--------------|---------------------------------------------------------|
+| Sensapex     | <ul> <li>uMp-4</li> <li>uMp-3 (Coming Soon!)</li> </ul> |
+| New Scale    | <ul> <li>Pathfinder MPM Control v2.8+</li> </ul>        |
+| Scientifica  | <ul> <li>InVivoStar (Coming Soon!)</li> </ul>           |
+| LabMaker     | <ul> <li>(Coming Soon!)</li> </ul>                      |
 
 Ephys Link is an open and extensible platform. It is designed to easily support integration with other manipulators.
 
@@ -45,10 +47,6 @@ the [API reference](https://virtualbrainlab.org/api_reference_ephys_link.html).
    connected to the computer. Follow the instructions on that repo for how to
    set up the Arduino.
 
-**NOTE:** Ephys Link is an HTTP server without cross-origin support. The server
-is currently designed to interface with local/desktop instances of Pinpoint. It
-will not work with the web browser versions of Pinpoint at this time.
-
 ## Launch from Pinpoint (Recommended)
 
 Pinpoint comes bundled with the correct version of Ephys Link. If you are using Pinpoint on the same computer your

docs/development/adding_a_manipulator.md

@@ -0,0 +1,52 @@
+By the end of this section, you will be able to add a manipulator platform to Ephys Link and control it using the server
+API. This is a software development guide and assumes you have experience with Python.
+
+## Set Up for Development
+
+1. Fork the [Ephys Link repository](https://github.com/VirtualBrainLab/ephys-link).
+2. Follow the instructions for [installing Ephys Link for development](index.md/#installing-for-development) to get all
+   the necessary dependencies and tools set up. In this case, you'll want to clone your fork.
+
+## Create a Manipulator Binding
+
+Manipulators are added to Ephys Link through bindings. A binding is a Python class that extends the abstract base class
+`BaseBinding` and defines the functions Ephys Link expects from a platform.
+
+Create a new Python module in `src/ephys_link/bindings` for your manipulator. Make a class that extends
+`BaseBinding`. Most IDEs will automatically import the necessary classes and tell you the methods you need to
+implement. These functions have signature documentation describing what they should do.
+
+As described in the [system overview](../home/how_it_works.md), Ephys Link converts all manipulator movement into a
+common "unified space" which is
+the [left-hand cartesian coordinate system](https://www.scratchapixel.com/lessons/mathematics-physics-for-computer-graphics/geometry/coordinate-systems.html).
+The two functions `platform_space_to_unified_space` and `unified_space_to_platform_space` are used to convert between
+your manipulator's coordinate system and the unified space.
+
+!!! tip
+
+    See
+    the [Sensapex uMp-4](https://github.com/VirtualBrainLab/ephys-link/blob/main/src/ephys_link/bindings/ump_4_bindings.py)
+    binding for an example where the platform has a Python API (Sensapex's SDK) and
+    the [New Scale Pathfinder MPM](https://github.com/VirtualBrainLab/ephys-link/blob/main/src/ephys_link/bindings/mpm_bindings.py)
+    binding for an example where the platform uses a REST API to an external provider.
+
+## Register the Binding
+
+To make Ephys Link aware of your new binding, you'll need to register it in
+`src/ephys_link/back_end/platform_handler.py`. In the function [
+`_match_platform_type`](https://github.com/VirtualBrainLab/ephys-link/blob/c00be57bb552e5d0466b1cfebd0a54d555f12650/src/ephys_link/back_end/platform_handler.py#L69),
+add a new `case` to the `match` statement that returns an instance of your binding when matched to the desired CLI name
+for your platform. For example, to use Sensapex's uMp-4 the CLI launch command is `ephys_link.exe -b -t ump-4`,
+therefore the matching case statement is `ump-4`.
+
+## Test Your Binding
+
+Once you've implemented your binding, you can test it by running Ephys Link using your binding
+`ephys_link -b -t <your_manipulator>`. You can interact with it using the Socket.IO API or Pinpoint.
+
+## Submit Your Changes
+
+When you're satisfied with your changes, submit a pull request to the main repository. We will review your changes and
+merge them if they meet our standards!
+
+Feel free to [reach out](../home/contact.md) to us if you have any questions or need help with your binding!

docs/development/code_organization.md

@@ -0,0 +1,3 @@
+!!! warning "Under Construction"
+
+    This documentation page is still under construction. Please come back later for more information!

docs/development/index.md

@@ -0,0 +1,26 @@
+# Developing with Ephys Link
+
+Ephys Link is free and open-source software. All of our code is available
+on [GitHub](https://github.com/VirtualBrainLab/ephys-link), and we welcome contributions from the community!
+
+This section describes:
+
+- [The Socket.IO server's API](socketio_api.md) and how to communicate with Ephys Link from a client application
+- How to [add a new manipulator](adding_a_manipulator.md) to Ephys Link
+- General [code organization](code_organization.md) and development practices for Ephys Link
+
+## Installing for Development
+
+1. Clone the repository.
+2. Install [Hatch](https://hatch.pypa.io/latest/install/)
+3. In a terminal, navigate to the repository's root directory and run
+
+   ```bash
+   hatch shell
+   ```
+
+This will create a virtual environment, install Python 13 (if not found), and install the package in editable mode.
+
+If you encounter any dependency issues (particularly with `aiohttp`), try installing the latest Microsoft Visual C++
+(MSVC v143+ x86/64) and the Windows SDK (10/11)
+via [Visual Studio Build Tools Installer](https://visualstudio.microsoft.com/visual-cpp-build-tools/).

docs/development/socketio_api.md

@@ -0,0 +1,7 @@
+This section documents the Socket.IO API. The document is intended for developers building client applications that
+communicate with the server. If you are looking for information on how to set up and run the server, see the
+[installation guide](../home/installation.md)!
+
+!!! warning "Under Construction"
+
+    This documentation page is still under construction. Please come back later for more information!

docs/home/contact.md

@@ -0,0 +1,6 @@
+Kenneth J. Yang is the primary developer and maintainer of Ephys Link. You can find his contact information on the
+VBL [about page](https://virtualbrainlab.org/about/overview.html) along with Daniel Birman's (the co-developer of Ephys Link).
+
+As an open source project, we welcome [bug reports](https://github.com/VirtualBrainLab/ephys-link/issues)
+and [discussions](https://github.com/VirtualBrainLab/ephys-link/discussions) on
+our [GitHub page](https://github.com/VirtualBrainLab/ephys-link)!

docs/home/how_it_works.md

@@ -0,0 +1,7 @@
+This section provides an overview of how Ephys Link works. It is intended for users who want to understand the
+software's architecture and how it interacts with other systems.
+
+!!! warning "Under Construction"
+
+    This documentation page is still under construction. Please come back later for more information!
+

docs/home/installation.md

@@ -0,0 +1,37 @@
+## Prerequisites
+
+1. An **x86 Windows PC is required** to run the server.
+2. For Sensapex devices, the controller unit must be connected via an ethernet
+   cable and powered. A USB-to-ethernet adapter is acceptable. For New Scale manipulators,
+   the controller unit must be connected via USB and be powered by a 6V power
+   supply.
+3. To use the emergency stop feature, ensure an Arduino with
+   the [StopSignal](https://github.com/VirtualBrainLab/StopSignal) sketch is
+   connected to the computer. Follow the instructions on that repo for how to
+   set up the Arduino.
+
+## Pinpoint (Recommended Method)
+
+Pinpoint comes bundled with the correct version of Ephys Link. If you are using Pinpoint on the same computer your
+manipulators are connected to, you can launch the server from within Pinpoint. See documentation
+on [connecting from Pinpoint](../usage/connecting_to_pinpoint.md).
+
+## Install as a Standalone Executable
+
+Download the latest executable from the [releases page](https://github.com/VirtualBrainLab/ephys-link/releases/latest).
+
+## Install as a Python package
+
+```bash
+pip install ephys-link
+```
+
+or with [pipx](https://pipx.pypa.io/stable/) (recommended)
+
+```bash
+pipx install ephys-link
+```
+
+## Install for Development
+
+See [development documentation](../development/index.md/#installing-for-development) for more information.

docs/home/supported_manipulators.md

@@ -0,0 +1,10 @@
+This is a current list of planned and supported manipulators in Ephys Link. If you use a manipulator that is not listed
+here, we suggest reaching out to your manipulator's manufacturer to request support for Ephys Link. Direct them to
+contact [Kenneth Yang and Daniel Birman](https://virtualbrainlab.org/about/overview.html)!
+
+| Manufacturer | Model                                                   |
+|--------------|---------------------------------------------------------|
+| Sensapex     | <ul> <li>uMp-4</li> <li>uMp-3 (Coming Soon!)</li> </ul> |
+| New Scale    | <ul> <li>Pathfinder MPM Control v2.8+</li> </ul>        |
+| Scientifica  | <ul> <li>InVivoStar (Coming Soon!)</li> </ul>           |
+| LabMaker     | <ul> <li>(Coming Soon!)</li> </ul>                      |

docs/index.md

@@ -0,0 +1,51 @@
+# Electrophysiology Manipulator Link
+
+[![PyPI version](https://badge.fury.io/py/ephys-link.svg)](https://badge.fury.io/py/ephys-link)
+[![CodeQL](https://github.com/VirtualBrainLab/ephys-link/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/VirtualBrainLab/ephys-link/actions/workflows/codeql-analysis.yml)
+[![Dependency Review](https://github.com/VirtualBrainLab/ephys-link/actions/workflows/dependency-review.yml/badge.svg)](https://github.com/VirtualBrainLab/ephys-link/actions/workflows/dependency-review.yml)
+[![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+The [Electrophysiology Manipulator Link](https://github.com/VirtualBrainLab/ephys-link)
+(or Ephys Link for short) is a Python [Socket.IO](https://socket.io/docs/v4/#what-socketio-is) server that allows any
+Socket.IO-compliant application (such
+as [Pinpoint](https://github.com/VirtualBrainLab/Pinpoint))
+to communicate with manipulators used in electrophysiology experiments.
+
+<img width="100%" src="https://github.com/VirtualBrainLab/ephys-link/assets/82800265/0c7c60b1-0926-4697-a461-221554f82de1" alt="Manipulator and probe in pinpoint moving in sync">
+
+<div class="grid cards" markdown>
+
+-   __:fontawesome-solid-download: Get Started__
+
+    ---
+
+    Install Ephys Link and get started in seconds
+
+
+    [:octicons-arrow-right-24: Install](home/installation.md)
+
+-   __:fontawesome-solid-computer: Usage__
+
+    ---
+
+    Learn how to use Ephys Link to control your manipulators
+
+    [:octicons-arrow-right-24: Usage](usage/index.md)
+
+-   __:fontawesome-regular-square-plus: Add a Manipulator Platform__
+
+    ---
+
+    Add a new manipulator platform to Ephys Link to enable control
+
+    [:octicons-arrow-right-24: Develop](development/adding_a_manipulator.md)
+
+-   __:fontawesome-solid-book-open: Learn About Pinpoint__
+
+    ---
+
+    Pinpoint is an experiment planning and automation tool that uses Ephys Link
+
+    [:octicons-arrow-right-24: Learn More](https://virtualbrainlab.org/pinpoint/installation_and_use.html)
+</div>

docs/stylesheets/extra.css

@@ -0,0 +1,5 @@
+:root {
+    --md-primary-fg-color: #0FBBBB;
+    --md-primary-fg-color--light: #0FBBBB;
+    --md-primary-fg-color--dark: #0FBBBB;
+}

docs/usage/connecting_to_pinpoint.md

@@ -0,0 +1,6 @@
+[Pinpoint](https://github.com/VirtualBrainLab/Pinpoint) is a tool for planning electrophysiology recordings and other
+_in vivo_ insertions, as well as tracking the position of probes in real-time inside the brain.
+
+Ephys Link was developed alongside Pinpoint to facilitate tracking and positioning of manipulators. Follow the
+[instructions on Pinpoint's documentation](https://virtualbrainlab.org//pinpoint/tutorials/tutorial_ephys_link.html) to
+use Ephys Link inside Pinpoint!

docs/usage/experiment_automation.md

@@ -0,0 +1,8 @@
+Pinpoint and Ephys Link can work together to automate manual procedures in electrophysiology experiments. Follow the
+[instructions on Pinpoint's documentation](https://virtualbrainlab.org//pinpoint/tutorials/tutorial_ephys_copilot.html)
+to use automation in your next experiment!
+
+!!! note
+
+    Automation is still in early development. We recommend [contacting](https://virtualbrainlab.org/about/overview.html)
+    Dan Birman and Kenneth Yang if you would like to try it out!