Merge branch 'main' into pipeline

.env.sample

@@ -1,2 +1,2 @@
-MINISCOPE_IO_BASE_DIR="~/.config/miniscope_io"
-MINISCOPE_IO_LOGS__LEVEL="INFO"
+MIO_BASE_DIR="~/.config/mio"
+MIO_LOGS__LEVEL="INFO"

.github/workflows/docs-test.yml

@@ -0,0 +1,33 @@
+name: Build and test documentation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  test_docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v3
+
+      - name: Set up python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: pip install -e .[docs] pytest-md
+
+      - name: Build docs
+        working-directory: docs
+        env:
+          SPHINXOPTS: "-W --keep-going"
+        run: make html

README.md

@@ -1,10 +1,10 @@
-# miniscope-io
+# mio: Miniscope IO
 
-[![PyPI - Version](https://img.shields.io/pypi/v/miniscope-io)](https://pypi.org/project/miniscope_io/)
+[![PyPI - Version](https://img.shields.io/pypi/v/mio)](https://pypi.org/project/mio/)
 [![Documentation Status](https://readthedocs.org/projects/miniscope-io/badge/?version=latest)](https://miniscope-io.readthedocs.io/en/latest/?badge=latest)
-![PyPI - Python Version](https://img.shields.io/pypi/pyversions/miniscope-io)
-![PyPI - Status](https://img.shields.io/pypi/status/miniscope-io)
-[![Coverage Status](https://coveralls.io/repos/github/Aharoni-Lab/miniscope-io/badge.svg?branch=main)](https://coveralls.io/github/Aharoni-Lab/miniscope-io?branch=main)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mio)
+![PyPI - Status](https://img.shields.io/pypi/status/mio)
+[![Coverage Status](https://coveralls.io/repos/github/Aharoni-Lab/mio/badge.svg?branch=main)](https://coveralls.io/github/Aharoni-Lab/mio?branch=main)
 
 Generic i/o interfaces for miniscopes.
 
@@ -21,4 +21,4 @@ restrictive licenses. Those licenses can be found
 in the `LICENSE` files in the respective directories 
 containing the unmodified source material
 
-* `miniscope_io/vendor/opalkelly` 
+* `mio/vendor/opalkelly` 

docs/api/bit_operation.md

@@ -1,7 +1,7 @@
 # bit operation
 
 ```{eval-rst}
-.. automodule:: miniscope_io.bit_operation
+.. automodule:: mio.bit_operation
     :members:
     :private-members:
 ```

docs/api/exceptions.md

@@ -1,7 +1,7 @@
 # exceptions
 
 ```{eval-rst}
-.. automodule:: miniscope_io.exceptions
+.. automodule:: mio.exceptions
     :members:
     :undoc-members:
 ```

docs/api/io.md

@@ -1,7 +1,7 @@
 # io
 
 ```{eval-rst}
-.. automodule:: miniscope_io.io
+.. automodule:: mio.io
     :members:
     :undoc-members:
 ```

docs/api/logging.md

@@ -1,7 +1,7 @@
 # logging
 
 ```{eval-rst}
-.. automodule:: miniscope_io.logging
+.. automodule:: mio.logging
     :members:
     :undoc-members:
 ```

docs/api/models/buffer.md

@@ -1,7 +1,7 @@
 # buffer
 
 ```{eval-rst}
-.. automodule:: miniscope_io.models.buffer
+.. automodule:: mio.models.buffer
     :members:
     :undoc-members:
 ```

docs/api/models/config.md

@@ -1,7 +1,7 @@
 # config
 
 ```{eval-rst}
-.. automodule:: miniscope_io.models.config
+.. automodule:: mio.models.config
     :members:
     :undoc-members:
 ```

docs/api/models/data.md

@@ -1,7 +1,7 @@
 # data
 
 ```{eval-rst}
-.. automodule:: miniscope_io.data
+.. automodule:: mio.data
     :members:
     :undoc-members:
 ```

docs/api/models/index.md

@@ -1,13 +1,20 @@
 # models
 
-Pydantic models used throughout `miniscope_io`.
+Pydantic models used throughout `mio`.
 
 These models should be kept as generic as possible, and any refinements
 needed for a specific acquisition class should be defined within that
 module, inheriting from the relevant parent class. Rule of thumb: 
 keep what is common common, and what is unique unique.
 
 
+
+```{eval-rst}
+.. automodule:: mio.models
+    :members:
+    :undoc-members:
+```
+
 ```{toctree}
 :maxdepth: 1
 

docs/api/models/mixins.md

@@ -1,7 +1,7 @@
 # mixins
 
 ```{eval-rst}
-.. automodule:: miniscope_io.models.mixins
+.. automodule:: mio.models.mixins
     :members:
     :undoc-members:
 ```

docs/api/models/models.md

@@ -1,7 +1,7 @@
 # models
 
 ```{eval-rst}
-.. automodule:: miniscope_io.models.models
+.. automodule:: mio.models.models
     :members:
     :undoc-members:
 ```

docs/api/models/sdcard.md

@@ -1,7 +1,7 @@
 # sdcard
 
 ```{eval-rst}
-.. automodule:: miniscope_io.models.sdcard
+.. automodule:: mio.models.sdcard
     :members:
     :undoc-members:
 ```

docs/api/models/stream.md

@@ -1,7 +1,7 @@
 # stream
 
 ```{eval-rst}
-.. automodule:: miniscope_io.models.stream
+.. automodule:: mio.models.stream
     :members:
     :undoc-members:
 ```

docs/api/plots/headers.md

@@ -1,7 +1,7 @@
 # headers
 
 ```{eval-rst}
-.. automodule:: miniscope_io.plots.headers
+.. automodule:: mio.plots.headers
     :members:
     :undoc-members:
 ```

docs/api/stream_daq.md

@@ -2,13 +2,13 @@
 This module is a data acquisition module that captures video streams from Miniscopes based on the `Miniscope-SAMD-Framework` firmware. The firmware repository will be published in future updates but is currently under development and private.
 
 ## Command
-After [installation](../guide/installation.md) and customizing [device configurations](stream-dev-config) and [runtime configuration](models/config.md) if necessary, run the command described in [CLI Usage](../guide/cli).
+After [installation](../guide/installation.md) and customizing [device configurations](stream-dev-config) and [runtime configuration](models/config.md) if necessary, run the command described in [CLI Usage](../cli/index).
 
 One example of this command is the following:
 ```bash
 $ mio stream capture -c .path/to/device/config.yml -o output_filename.avi -m
 ```
-A window displaying the image transferred from the Miniscope and a graph plotting metadata (`-m` option) should pop up. Additionally, the indexes of captured frames and their statuses will be logged in the terminal. The `MINISCOPE_IO_STREAM_HEADER_PLOT_KEY` defines plotted header fields (see `.env.sample`).
+A window displaying the image transferred from the Miniscope and a graph plotting metadata (`-m` option) should pop up. Additionally, the indexes of captured frames and their statuses will be logged in the terminal. The `MIO_STREAM_HEADER_PLOT_KEY` defines plotted header fields (see `.env.sample`).
 
 ## Prerequisites
 - **Data capture hardware:** Opal Kelly XEM7310-A75 FPGA board (connected via USB)
@@ -17,10 +17,10 @@ A window displaying the image transferred from the Miniscope and a graph plottin
 
 (stream-dev-config)=
 ## Device configuration
-A YAML file is used to configure Stream DAQ based on the device configuration. The device configuration needs to match the imaging and data capture hardware for proper operation. This file is used to set up hardware, define data formats, and set data preambles. The contents of this YAML file will be parsed into a model [miniscope_io.models.stream](../api/models/stream.md), which then configures the Stream DAQ.
+A YAML file is used to configure Stream DAQ based on the device configuration. The device configuration needs to match the imaging and data capture hardware for proper operation. This file is used to set up hardware, define data formats, and set data preambles. The contents of this YAML file will be parsed into a model [mio.models.stream](../api/models/stream.md), which then configures the Stream DAQ.
 
 ### FPGA (Opal Kelly) configuration
-The `bitstream` field in the device configuration yaml file specifies the image that will be uploaded to the opal kelly board. This file needs to be placed in `miniscope_io.devices`.
+The `bitstream` field in the device configuration yaml file specifies the image that will be uploaded to the opal kelly board. This file needs to be placed in `mio.devices`.
 
 
 #### Bitstream file nomenclature
@@ -33,7 +33,7 @@ Name format of the bitstream files and directory:
 - **ENCODING_POLARITY**: Manchester encoding convention, which corresponds to bit polarity. The current package supports IEEE convention Manchester encoding.
 
 ### Example device configuration
-Below is an example configuration YAML file. More examples can be found in `miniscope_io.data.config`.
+Below is an example configuration YAML file. More examples can be found in `mio.data.config`.
 
 ```yaml
 # capture device. "OK" (Opal Kelly) or "UART"
@@ -91,7 +91,7 @@ runtime:
 ```
 
 ```{eval-rst}
-.. automodule:: miniscope_io.stream_daq
+.. automodule:: mio.stream_daq
     :members:
     :undoc-members:
 ```

docs/api/utils.md

@@ -1,7 +1,7 @@
 # utils
 
 ```{eval-rst}
-.. automodule:: miniscope_io.utils
+.. automodule:: mio.utils
     :members:
     :undoc-members:
 ```

docs/cli/config.md

@@ -0,0 +1,9 @@
+# `config`
+
+See also: [config guide](../guide/config.md)
+
+```{eval-rst}
+.. click:: mio.cli.config:config
+    :prog: mio config
+    :nested: full
+```

docs/cli/device.md

@@ -0,0 +1,6 @@
+# `device`
+
+```{eval-rst}
+.. click:: mio.cli.main:device
+    :prog: mio device
+```

docs/cli/index.md

@@ -0,0 +1,19 @@
+# CLI Usage
+
+```{toctree}
+:maxdepth: 1
+
+config
+device
+stream
+update
+```
+
+Refer to the following page for details regarding ``stream_daq`` device config files.
+
+- [stream_daq](../api/stream_daq.md)
+
+```{eval-rst}
+.. click:: mio.cli.main:cli
+    :prog: mio
+```

docs/cli/stream.md

@@ -0,0 +1,7 @@
+# `stream`
+
+```{eval-rst}
+.. click:: mio.cli.stream:stream
+    :prog: mio stream
+    :nested: full
+```

docs/cli/update.md

@@ -0,0 +1,7 @@
+# `update`
+
+```{eval-rst}
+.. click:: mio.cli.update:update
+    :prog: mio update
+    :nested: full
+```

docs/conf.py

@@ -17,8 +17,8 @@
 project = "miniscope-io"
 copyright = "2023, Jonny"
 author = "Jonny, Takuya"
-release = _version("miniscope-io")
-html_title = "miniscope-io"
+release = _version("mio")
+html_title = "mio"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -32,8 +32,10 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx_click",
+    "sphinx_design",
     "sphinxcontrib.autodoc_pydantic",
     "sphinxcontrib.mermaid",
+    "sphinxcontrib.programoutput",
 ]
 
 templates_path = ["_templates"]
@@ -44,7 +46,6 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "furo"
-html_static_path = ["_static"]
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),

docs/guide/capture/wireless.md

@@ -8,8 +8,8 @@
 
 ## Header Values and Expected Transitions
 See following docs for the basic structure.
-- `miniscope_io.models.buffer.BufferHeaderFormat`
-- `miniscope_io.models.stream.StreamBufferHeaderFormat`
+- `mio.models.buffer.BufferHeaderFormat`
+- `mio.models.stream.StreamBufferHeaderFormat`
 
 Device specific notes are listed below.
 - **`preamble`**: 32-bit preamble for detecting the beginning of each buffer. The [`preamble`](../../api/stream_daq.md) in the device config needs to match the preamble defined in firmware.