Skip to content

Commit 362e1f3

Browse files
kjy5kjy5
authored
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
1 parent b0df1a8 commit 362e1f3

23 files changed

+468
-89
lines changed

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,5 +38,5 @@ jobs:
3838
- name: 🧶 Lint
3939
run: hatch fmt --check
4040

41-
- name: 🔍 Type Check
42-
run: hatch -e types run check
41+
# - name: 🔍 Type Check
42+
# run: hatch -e types run check

‎.github/workflows/build-docs.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: Build Documentation
2+
3+
on:
4+
pull_request:
5+
branches: [ "main" ]
6+
workflow_dispatch:
7+
workflow_call:
8+
9+
jobs:
10+
build:
11+
name: Build
12+
13+
runs-on: ubuntu-latest
14+
15+
steps:
16+
- name: 🛎 Checkout
17+
uses: actions/checkout@v4
18+
with:
19+
ref: ${{ github.head_ref }}
20+
21+
- name: 🐍 Setup Python
22+
uses: actions/setup-python@v5
23+
with:
24+
python-version: "3.13"
25+
cache: "pip"
26+
27+
- name: 📦 Install Hatch
28+
uses: pypa/hatch@install
29+
30+
- name: 🔨 Build Documentation
31+
run: hatch -e docs run build
32+
33+
- name: ⬆️ Upload Artifacts
34+
uses: actions/upload-pages-artifact@v3
35+
with:
36+
path: "site"

‎.github/workflows/deploy-docs.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches: [ "main" ]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: "deploy-docs"
15+
cancel-in-progress: true
16+
17+
jobs:
18+
19+
build:
20+
name: Build
21+
uses: ./.github/workflows/build-docs.yml
22+
23+
deploy:
24+
name: Deploy Documentation
25+
26+
needs: build
27+
28+
environment:
29+
name: github-pages
30+
url: ${{ steps.deployment.outputs.page_url }}
31+
32+
runs-on: ubuntu-latest
33+
34+
steps:
35+
36+
- name: 🎛 Setup Pages
37+
uses: actions/configure-pages@v5
38+
39+
- name: 🚀 Deploy to GitHub Pages
40+
id: deployment
41+
uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -8,20 +8,22 @@
88

99
<!-- [![Build](https://github.com/VirtualBrainLab/ephys-link/actions/workflows/build.yml/badge.svg)](https://github.com/VirtualBrainLab/ephys-link/actions/workflows/build.yml) -->
1010

11-
<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">
12-
1311
The [Electrophysiology Manipulator Link](https://github.com/VirtualBrainLab/ephys-link)
1412
(or Ephys Link for short) is a Python [Socket.IO](https://socket.io/docs/v4/#what-socketio-is) server that allows any
1513
Socket.IO-compliant application (such
1614
as [Pinpoint](https://github.com/VirtualBrainLab/Pinpoint))
1715
to communicate with manipulators used in electrophysiology experiments.
1816

17+
<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">
18+
1919
**Supported Manipulators:**
2020

21-
| Manufacturer | Model |
22-
|--------------|-------------------------------------------------------------------------|
23-
| Sensapex | <ul> <li>uMp-4</li> <li>uMp-3</li> </ul> |
24-
| New Scale | <ul> <li>Pathfinder MPM Control v2.8+</li> <li>M3-USB-3:1-EP</li> </ul> |
21+
| Manufacturer | Model |
22+
|--------------|---------------------------------------------------------|
23+
| Sensapex | <ul> <li>uMp-4</li> <li>uMp-3 (Coming Soon!)</li> </ul> |
24+
| New Scale | <ul> <li>Pathfinder MPM Control v2.8+</li> </ul> |
25+
| Scientifica | <ul> <li>InVivoStar (Coming Soon!)</li> </ul> |
26+
| LabMaker | <ul> <li>(Coming Soon!)</li> </ul> |
2527

2628
Ephys Link is an open and extensible platform. It is designed to easily support integration with other manipulators.
2729

@@ -45,10 +47,6 @@ the [API reference](https://virtualbrainlab.org/api_reference_ephys_link.html).
4547
connected to the computer. Follow the instructions on that repo for how to
4648
set up the Arduino.
4749

48-
**NOTE:** Ephys Link is an HTTP server without cross-origin support. The server
49-
is currently designed to interface with local/desktop instances of Pinpoint. It
50-
will not work with the web browser versions of Pinpoint at this time.
51-
5250
## Launch from Pinpoint (Recommended)
5351

5452
Pinpoint comes bundled with the correct version of Ephys Link. If you are using Pinpoint on the same computer your

assets/icon.ico renamed to docs/assets/favicon.ico

File renamed without changes.

‎docs/assets/icon.png‎

8.07 KB
Loading

‎docs/development/adding_a_manipulator.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
By the end of this section, you will be able to add a manipulator platform to Ephys Link and control it using the server
2+
API. This is a software development guide and assumes you have experience with Python.
3+
4+
## Set Up for Development
5+
6+
1. Fork the [Ephys Link repository](https://github.com/VirtualBrainLab/ephys-link).
7+
2. Follow the instructions for [installing Ephys Link for development](index.md/#installing-for-development) to get all
8+
the necessary dependencies and tools set up. In this case, you'll want to clone your fork.
9+
10+
## Create a Manipulator Binding
11+
12+
Manipulators are added to Ephys Link through bindings. A binding is a Python class that extends the abstract base class
13+
`BaseBinding` and defines the functions Ephys Link expects from a platform.
14+
15+
Create a new Python module in `src/ephys_link/bindings` for your manipulator. Make a class that extends
16+
`BaseBinding`. Most IDEs will automatically import the necessary classes and tell you the methods you need to
17+
implement. These functions have signature documentation describing what they should do.
18+
19+
As described in the [system overview](../home/how_it_works.md), Ephys Link converts all manipulator movement into a
20+
common "unified space" which is
21+
the [left-hand cartesian coordinate system](https://www.scratchapixel.com/lessons/mathematics-physics-for-computer-graphics/geometry/coordinate-systems.html).
22+
The two functions `platform_space_to_unified_space` and `unified_space_to_platform_space` are used to convert between
23+
your manipulator's coordinate system and the unified space.
24+
25+
!!! tip
26+
27+
See
28+
the [Sensapex uMp-4](https://github.com/VirtualBrainLab/ephys-link/blob/main/src/ephys_link/bindings/ump_4_bindings.py)
29+
binding for an example where the platform has a Python API (Sensapex's SDK) and
30+
the [New Scale Pathfinder MPM](https://github.com/VirtualBrainLab/ephys-link/blob/main/src/ephys_link/bindings/mpm_bindings.py)
31+
binding for an example where the platform uses a REST API to an external provider.
32+
33+
## Register the Binding
34+
35+
To make Ephys Link aware of your new binding, you'll need to register it in
36+
`src/ephys_link/back_end/platform_handler.py`. In the function [
37+
`_match_platform_type`](https://github.com/VirtualBrainLab/ephys-link/blob/c00be57bb552e5d0466b1cfebd0a54d555f12650/src/ephys_link/back_end/platform_handler.py#L69),
38+
add a new `case` to the `match` statement that returns an instance of your binding when matched to the desired CLI name
39+
for your platform. For example, to use Sensapex's uMp-4 the CLI launch command is `ephys_link.exe -b -t ump-4`,
40+
therefore the matching case statement is `ump-4`.
41+
42+
## Test Your Binding
43+
44+
Once you've implemented your binding, you can test it by running Ephys Link using your binding
45+
`ephys_link -b -t <your_manipulator>`. You can interact with it using the Socket.IO API or Pinpoint.
46+
47+
## Submit Your Changes
48+
49+
When you're satisfied with your changes, submit a pull request to the main repository. We will review your changes and
50+
merge them if they meet our standards!
51+
52+
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‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
!!! warning "Under Construction"
2+
3+
This documentation page is still under construction. Please come back later for more information!

‎docs/development/index.md‎

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

‎docs/development/socketio_api.md‎

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

0 commit comments

Comments
 (0)