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]>

Author: kjy5

.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/assets/favicon.ico

@@ -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.