feat: documentation (#64)

* Update README with install and badges

* Bootstrap documentation

* Usage documentation

* Source Code documentation

* Index grids

* GitHub Action

* chore: Build Models

* chore: Autoformat code

---------

Co-authored-by: kjy5 <[email protected]>

.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

@@ -1,5 +1,40 @@
-# VBL Aquarium
+# Virtual Brain Lab Aquarium
 
-Collection of Pydantic models describing data objects passed between Virtual Brain Lab projects.
+![PyPI - Version](https://img.shields.io/pypi/v/vbl-aquarium)
+[![Build Models](https://github.com/VirtualBrainLab/vbl-aquarium/actions/workflows/build-models.yml/badge.svg)](https://github.com/VirtualBrainLab/vbl-aquarium/actions/workflows/build-models.yml)
+[![Static Analysis](https://github.com/VirtualBrainLab/vbl-aquarium/actions/workflows/static-analysis.yml/badge.svg)](https://github.com/VirtualBrainLab/vbl-aquarium/actions/workflows/static-analysis.yml)
+[![Pydantic v2](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json)](https://pydantic.dev)
+[![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)
+[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
 
-Corresponding JSON schema and C# .cs struct files are generated automatically with the command `python build.py`
+Collection of Pydantic models describing data objects passed between Virtual
+Brain Lab projects.
+
+Corresponding JSON schema and C# files are generated automatically and are
+located in the `models` directory.
+
+## Usage
+
+For C# structs or JSON schemas, copy or reference whatever models you need from
+the `models` directory.
+
+To use the Pydantic models directly in Python, install the package with
+
+```bash
+pip install vbl-aquarium
+```
+
+Then import the models with
+
+```python
+from vbl_aquarium.models.module_name import ModelName
+```
+
+replacing `.module_name` and `ModelName` with the desired model.
+
+## Further Documentation
+
+For more information regarding updating models and each model's specification,
+see the VBL
+Aquarium [documentation](https://virtualbrainlab.github.io/vbl-aquarium/).

docs/api/ephys_link.md

@@ -0,0 +1 @@
+::: vbl_aquarium.models.ephys_link

docs/api/index.md

@@ -0,0 +1,8 @@
+# Model API
+
+This section documents each model's API. These are autogenerated using the
+model's docstrings.
+
+!!! warning
+
+    Not all models have complete docstring documentation yet. Please come back later for updates!

docs/api/unity_models.md

@@ -0,0 +1 @@
+::: vbl_aquarium.utils.unity_models

docs/api/vbl_base_model.md

@@ -0,0 +1 @@
+::: vbl_aquarium.utils.vbl_base_model

docs/development/index.md

@@ -0,0 +1,28 @@
+# Developing VBL Aquarium
+
+[GitHub Actions](https://github.com/VirtualBrainLab/vbl-aquarium/actions/workflows/build-models.yml)
+are used to automatically build models to the `models` directory.
+To update the models, simply push changes to the underlying pydantic models in
+the `vbl_aquarium/models` directory.
+
+## Local Development Setup
+
+1. Install [Hatch](https://hatch.pypa.io/latest/)
+2. Clone the repository
+3. Run `hatch shell` in the repository root directory
+
+Use
+
+```bash
+python src/vbl_aquarium/build.py
+```
+
+to build the models locally.
+
+Use
+
+```bash
+hatch run check
+```
+
+to run pyright type checking.

docs/development/source_code_documentation/build.md

@@ -0,0 +1 @@
+::: vbl_aquarium.build

docs/development/source_code_documentation/common.md

@@ -0,0 +1 @@
+::: vbl_aquarium.utils.common

docs/development/source_code_documentation/generate_csharp.md

@@ -0,0 +1 @@
+::: vbl_aquarium.utils.generate_csharp

docs/development/source_code_documentation/index.md

@@ -0,0 +1,4 @@
+# Source Code Documentation
+
+The following sections are generated documentation from the source code. It is
+intended for developers who are maintaining for extending the build pipeline.

docs/home/usage.md

@@ -0,0 +1,16 @@
+For C# structs or JSON schemas, copy or reference whatever models you need from
+the `models` directory.
+
+To use the Pydantic models directly in Python, install the package with
+
+```bash
+pip install vbl-aquarium
+```
+
+Then import the models with
+
+```python
+from vbl_aquarium.models.module_name import ModelName
+```
+
+replacing `.module_name` and `ModelName` with the desired model.

docs/index.md

@@ -0,0 +1,42 @@
+# Virtual Brain Lab Aquarium
+
+![PyPI - Version](https://img.shields.io/pypi/v/vbl-aquarium)
+[![Build Models](https://github.com/VirtualBrainLab/vbl-aquarium/actions/workflows/build-models.yml/badge.svg)](https://github.com/VirtualBrainLab/vbl-aquarium/actions/workflows/build-models.yml)
+[![Static Analysis](https://github.com/VirtualBrainLab/vbl-aquarium/actions/workflows/static-analysis.yml/badge.svg)](https://github.com/VirtualBrainLab/vbl-aquarium/actions/workflows/static-analysis.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)
+[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
+
+Collection of Pydantic models describing data objects passed between Virtual
+Brain Lab projects.
+
+Corresponding JSON schema and C# files are generated automatically and are
+located in the `models` directory.
+
+<div class="grid cards" markdown>
+
+-   __:fontawesome-solid-computer: Usage__
+
+    ---
+
+    Learn how to use VBL Aquarium in your project
+
+    [:octicons-arrow-right-24: Usage](home/usage.md)
+
+-   __:fontawesome-solid-code: Develop Models__
+
+    ---
+
+    Install VBL Aquarium locally to develop new models
+
+    [:octicons-arrow-right-24: Install](development/index.md)
+
+
+-   __:material-api: API Reference__
+
+    ---
+
+    View the API reference for the models
+
+    [:octicons-arrow-right-24: API](api/index.md)
+</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;
+}

mkdocs.yml

@@ -0,0 +1,93 @@
+# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
+
+site_name: VBL Aquarium
+site_url: https://virtualbrainlab.github.io/vbl-aquarium
+repo_url: https://github.com/VirtualBrainLab/vbl-aquarium
+repo_name: virtualbrainlab/vbl-aquarium
+copyright: Copyright © 2024 Virtual Brain Lab
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/VirtualBrainLab/vbl-aquarium
+    - icon: fontawesome/brands/python
+      link: https://pypi.org/project/vbl-aquarium
+    - icon: fontawesome/solid/globe
+      link: https://virtualbrainlab.org
+theme:
+  name: material
+  logo: assets/icon.png
+  favicon: assets/favicon.ico
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: custom
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: custom
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+  features:
+    - content.code.copy
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.sections
+    - navigation.indexes
+    - toc.follow
+extra_css:
+  - stylesheets/extra.css
+markdown_extensions:
+  - admonition
+  - attr_list
+  - md_in_html
+  - pymdownx.details
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [ src ]
+          options:
+            docstring_style: google
+nav:
+  - Home:
+      - index.md
+      - Usage: home/usage.md
+  - Development:
+      - development/index.md
+      - "Source Code Documentation":
+          - development/source_code_documentation/index.md
+          - "build.py": development/source_code_documentation/build.md
+          - "utils/generate_csharp.py": development/source_code_documentation/generate_csharp.md
+          - "utils/common.py": development/source_code_documentation/common.md
+  - API:
+      - api/index.md
+      - "VBL Base Model": api/vbl_base_model.md
+      - "Unity": api/unity_models.md
+      - "Ephys Link": api/ephys_link.md

models/schemas/ephys_link/AngularResponse.json

@@ -1 +1 @@
-{"$defs": {"Vector3": {"properties": {"x": {"default": 0.0, "title": "X", "type": "number"}, "y": {"default": 0.0, "title": "Y", "type": "number"}, "z": {"default": 0.0, "title": "Z", "type": "number"}}, "title": "Vector3", "type": "object"}}, "description": "Response format for the manipulator angles.\n\n:param angles: Position of the manipulator.\n:type angles: Vector3", "properties": {"Angles": {"$ref": "#/$defs/Vector3", "default": {"x": 0.0, "y": 0.0, "z": 0.0}}, "Error": {"default": "", "title": "Error", "type": "string"}}, "title": "AngularResponse", "type": "object"}
+{"$defs": {"Vector3": {"description": "3D vector.\n\nAttributes:\n    x: X component.\n    y: Y component.\n    z: Z component.", "properties": {"x": {"default": 0.0, "title": "X", "type": "number"}, "y": {"default": 0.0, "title": "Y", "type": "number"}, "z": {"default": 0.0, "title": "Z", "type": "number"}}, "title": "Vector3", "type": "object"}}, "description": "Response format for the manipulator angles.\n\nAttributes:\n    angles: Position of the manipulator.\n    error: Error message if any.", "properties": {"Angles": {"$ref": "#/$defs/Vector3", "default": {"x": 0.0, "y": 0.0, "z": 0.0}}, "Error": {"default": "", "title": "Error", "type": "string"}}, "title": "AngularResponse", "type": "object"}

models/schemas/ephys_link/BooleanStateResponse.json

@@ -1 +1 @@
-{"description": "Response format for a boolean state.\n\n:param state: State of the event.\n:type state: bool\n:param error: Error message if any.\n:type error: str", "properties": {"State": {"default": false, "title": "State", "type": "boolean"}, "Error": {"default": "", "title": "Error", "type": "string"}}, "title": "BooleanStateResponse", "type": "object"}
+{"description": "Response format for a boolean state.\n\nAttributes:\n    state: State of the event.\n    error: Error message if any.", "properties": {"State": {"default": false, "title": "State", "type": "boolean"}, "Error": {"default": "", "title": "Error", "type": "string"}}, "title": "BooleanStateResponse", "type": "object"}

models/schemas/ephys_link/EphysLinkOptions.json

@@ -1 +1 @@
-{"description": "Options for running Ephys Link.\n\n:param background: Whether to skip the GUI and run using CLI arguments.\n:type background: bool\n:param ignore_updates: Whether to ignore updates.\n:type ignore_updates: bool\n:param type: Type of manipulator platform to use.\n:type type: str\n:param debug: Whether to print debug messages.\n:type debug: bool\n:param use_proxy: Whether to use VBL proxy service.\n:type use_proxy: bool\n:param proxy_address: Address of the proxy service.\n:type proxy_address: str\n:param mpm_port: Port for New Scale MPM HTTP server.\n:type mpm_port: int\n:param serial: Serial port for emergency stop.\n:type serial: str", "properties": {"Background": {"default": false, "title": "Background", "type": "boolean"}, "IgnoreUpdates": {"default": false, "title": "Ignoreupdates", "type": "boolean"}, "Type": {"default": "ump-4", "title": "Type", "type": "string"}, "Debug": {"default": false, "title": "Debug", "type": "boolean"}, "UseProxy": {"default": false, "title": "Useproxy", "type": "boolean"}, "ProxyAddress": {"default": "proxy2.virtualbrainlab.org", "title": "Proxyaddress", "type": "string"}, "MpmPort": {"default": 8080, "maximum": 49151, "minimum": 1024, "title": "Mpmport", "type": "integer"}, "Serial": {"default": "no-e-stop", "title": "Serial", "type": "string"}}, "title": "EphysLinkOptions", "type": "object"}
+{"description": "Options for running Ephys Link.\n\nAttributes:\n    background: Whether to skip the GUI and run using CLI arguments.\n    ignore_updates: Whether to ignore updates.\n    type: Type of manipulator platform to use.\n    debug: Whether to print debug messages.\n    use_proxy: Whether to use VBL proxy service.\n    proxy_address: Address of the proxy service.\n    mpm_port: Port for New Scale MPM HTTP server.\n    serial: Serial port for emergency stop.", "properties": {"Background": {"default": false, "title": "Background", "type": "boolean"}, "IgnoreUpdates": {"default": false, "title": "Ignoreupdates", "type": "boolean"}, "Type": {"default": "ump-4", "title": "Type", "type": "string"}, "Debug": {"default": false, "title": "Debug", "type": "boolean"}, "UseProxy": {"default": false, "title": "Useproxy", "type": "boolean"}, "ProxyAddress": {"default": "proxy2.virtualbrainlab.org", "title": "Proxyaddress", "type": "string"}, "MpmPort": {"default": 8080, "maximum": 49151, "minimum": 1024, "title": "Mpmport", "type": "integer"}, "Serial": {"default": "no-e-stop", "title": "Serial", "type": "string"}}, "title": "EphysLinkOptions", "type": "object"}

models/schemas/ephys_link/GetManipulatorsResponse.json

@@ -1 +1 @@
-{"$defs": {"Vector4": {"properties": {"x": {"default": 0.0, "title": "X", "type": "number"}, "y": {"default": 0.0, "title": "Y", "type": "number"}, "z": {"default": 0.0, "title": "Z", "type": "number"}, "w": {"default": 0.0, "title": "W", "type": "number"}}, "title": "Vector4", "type": "object"}}, "description": "Response format for requesting available manipulators.\n\n:param manipulators: List of manipulators.\n:type manipulators: list[str]\n:param num_axes: Number of axes for the manipulators.\n:type num_axes: int\n:param dimensions: Dimensions of the manipulators (3-axis manipulators should set w to 0).\n:type dimensions: Vector4\n:param error: Error message if any.\n:type error: str", "properties": {"Manipulators": {"items": {"type": "string"}, "title": "Manipulators", "type": "array"}, "NumAxes": {"default": 0, "minimum": -1, "title": "Numaxes", "type": "integer"}, "Dimensions": {"$ref": "#/$defs/Vector4", "default": {"x": 0.0, "y": 0.0, "z": 0.0, "w": 0.0}}, "Error": {"default": "", "title": "Error", "type": "string"}}, "title": "GetManipulatorsResponse", "type": "object"}
+{"$defs": {"Vector4": {"description": "4D vector.\n\nAttributes:\n    x: X component.\n    y: Y component.\n    z: Z component.\n    w: W component.", "properties": {"x": {"default": 0.0, "title": "X", "type": "number"}, "y": {"default": 0.0, "title": "Y", "type": "number"}, "z": {"default": 0.0, "title": "Z", "type": "number"}, "w": {"default": 0.0, "title": "W", "type": "number"}}, "title": "Vector4", "type": "object"}}, "description": "Response format for requesting available manipulators.\n\nAttributes:\n    manipulators: List of manipulators.\n    num_axes: Number of axes for the manipulators.\n    dimensions: Dimensions of the manipulators (3-axis manipulators should set w to 0).\n    error: Error message if any.", "properties": {"Manipulators": {"items": {"type": "string"}, "title": "Manipulators", "type": "array"}, "NumAxes": {"default": 0, "minimum": -1, "title": "Numaxes", "type": "integer"}, "Dimensions": {"$ref": "#/$defs/Vector4", "default": {"x": 0.0, "y": 0.0, "z": 0.0, "w": 0.0}}, "Error": {"default": "", "title": "Error", "type": "string"}}, "title": "GetManipulatorsResponse", "type": "object"}

models/schemas/ephys_link/PositionalResponse.json

@@ -1 +1 @@
-{"$defs": {"Vector4": {"properties": {"x": {"default": 0.0, "title": "X", "type": "number"}, "y": {"default": 0.0, "title": "Y", "type": "number"}, "z": {"default": 0.0, "title": "Z", "type": "number"}, "w": {"default": 0.0, "title": "W", "type": "number"}}, "title": "Vector4", "type": "object"}}, "description": "Response format for the manipulator position.\n\n:param position: Position of the manipulator.\n:type position: Vector4\n:param error: Error message if any.\n:type error: str", "properties": {"Position": {"$ref": "#/$defs/Vector4", "default": {"x": 0.0, "y": 0.0, "z": 0.0, "w": 0.0}}, "Error": {"default": "", "title": "Error", "type": "string"}}, "title": "PositionalResponse", "type": "object"}
+{"$defs": {"Vector4": {"description": "4D vector.\n\nAttributes:\n    x: X component.\n    y: Y component.\n    z: Z component.\n    w: W component.", "properties": {"x": {"default": 0.0, "title": "X", "type": "number"}, "y": {"default": 0.0, "title": "Y", "type": "number"}, "z": {"default": 0.0, "title": "Z", "type": "number"}, "w": {"default": 0.0, "title": "W", "type": "number"}}, "title": "Vector4", "type": "object"}}, "description": "Response format for the manipulator position.\n\nAttributes:\n    position: Position of the manipulator.\n    error: Error message if any.", "properties": {"Position": {"$ref": "#/$defs/Vector4", "default": {"x": 0.0, "y": 0.0, "z": 0.0, "w": 0.0}}, "Error": {"default": "", "title": "Error", "type": "string"}}, "title": "PositionalResponse", "type": "object"}

models/schemas/ephys_link/SetDepthRequest.json

@@ -1 +1 @@
-{"description": "Request format for driving a manipulator to depth.\n\n:param manipulator_id: ID of the manipulator to move.\n:type manipulator_id: str\n:param depth: Depth to drive to in mm.\n:type depth: float\n:param speed: Speed to drive at in mm/s.\n:type speed: float", "properties": {"ManipulatorId": {"minLength": 1, "title": "Manipulatorid", "type": "string"}, "Depth": {"title": "Depth", "type": "number"}, "Speed": {"exclusiveMinimum": 0.0, "title": "Speed", "type": "number"}}, "required": ["ManipulatorId", "Depth", "Speed"], "title": "SetDepthRequest", "type": "object"}
+{"description": "Request format for driving a manipulator to depth.\n\nAttributes:\n    manipulator_id: ID of the manipulator to move.\n    depth: Depth to drive to in mm.\n    speed: Speed to drive at in mm/s.", "properties": {"ManipulatorId": {"minLength": 1, "title": "Manipulatorid", "type": "string"}, "Depth": {"title": "Depth", "type": "number"}, "Speed": {"exclusiveMinimum": 0.0, "title": "Speed", "type": "number"}}, "required": ["ManipulatorId", "Depth", "Speed"], "title": "SetDepthRequest", "type": "object"}