Skip to content

Commit

Permalink
docs: Create package documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
PrinceEGY committed Jan 8, 2025
1 parent b0d1585 commit 1377088
Showing 11 changed files with 274 additions and 0 deletions.
27 changes: 27 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
name: docs
on:
push:
branches:
- main
pull_request:
branches:
- main
permissions:
contents: write
jobs:
Docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: 3.x
- uses: actions/cache@v4
with:
key: ${{github.ref}}
path: .cache
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install mkdocs-material mkdocstrings mkdocs-include-markdown-plugin
- run: mkdocs gh-deploy --force
9 changes: 9 additions & 0 deletions docs/api/enums.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
::: mindwave.headset.ConnectionStatus
---

::: mindwave.utils.event_manager.EventType
---

::: mindwave.session.SessionSignal
options:
show_if_no_docstring: true
35 changes: 35 additions & 0 deletions docs/api/events.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
::: mindwave.connector.ConnectorDataEvent
options:
show_docstring_parameters: false

---

::: mindwave.headset.HeadsetStatusEvent
options:
show_docstring_parameters: false
---

::: mindwave.utils.stream_parser.HeadsetDataEvent
options:
show_docstring_parameters: false
---

::: mindwave.headset.BlinkEvent
options:
show_docstring_parameters: false
---

::: mindwave.headset.SignalQualityEvent
options:
show_docstring_parameters: false
---

::: mindwave.headset.TimeoutEvent
options:
show_docstring_parameters: false
---

::: mindwave.session.SessionEvent
options:
show_docstring_parameters: false
---
8 changes: 8 additions & 0 deletions docs/api/headset.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
::: mindwave.utils.stream_parser.Data
options:
members: false
---

::: mindwave.headset.MindWaveMobile2
options:
show_docstring_functions: true
3 changes: 3 additions & 0 deletions docs/api/session.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
::: mindwave.session.SessionConfig

::: mindwave.session.Session
1 change: 1 addition & 0 deletions docs/api/tg_connector.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
::: mindwave.connector.ThinkGearConnector
109 changes: 109 additions & 0 deletions docs/examples.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
## Minimal working example
A minimal example to start a functional data collection session
```python linenums="1"
from pymindwave2 import MindWaveMobile2, Session, SessionConfig

# Initialize and connect to the headset
headset = MindWaveMobile2()
success = headset.start(n_tries=5, timeout=30)

if success: # if the headset is connected successfully
# Create a session configuration
sess_config = SessionConfig(
user_name="Ahmed",
classes=["left", "right"] # Define your classification tasks
)

# Initialize and start the recording session
session = Session(headset, config=sess_config)

while headset.signal_quality != 100:
pass # wait for the user to wear the headset properly

session.start() # Start recording data

while session.is_active:
pass # wait for the session to finish

session.save() # save the recorded data to disk
```
---
## Session Configuration attributes
```python linenums="1"
sess_config = SessionConfig(
user_name="Ahmed", # Name of the user
user_age=0, # Age of the user
classes=["left", "right", "foot"], # Classes used for motor imagery tasks
n_trials=10, # Number of trials for each class
capture_blinks=True, # Whether to capture blinks or not
motor_duration=5, # Duration of each motor imagery task in seconds
)
```
for the full list of attributes, check [SessionConfig](https://princeegy.github.io/pymindwave2/api/session/#mindwave.session.SessionConfig)
---
## Event Listeners
An example to subscribe to headset data emitted events
```python linenums="1"
from pymindwave2 import MindWaveMobile2, HeadsetDataEvent

headset = MindWaveMobile2()
success = headset.start(n_tries=5, timeout=30)

if sucess:
def meditation_handler(event: HeadsetDataEvent):
print(event.data.meditation)

subscription = headset.on_data(meditation_handler)

while some_condition:
pass

subscription.detach() # Unsubscribe from the event
```
An example to reconnect to the headset if the connection is lost
```python linenums="1"
... # headset connection
def reconnect_handler(event:HeadsetStatusEvent):
if event.status == ConnectionStatus.CONNECTION_LOST:
headset.start(n_tries=5, timeout=30)

subscription = headset.on_status_change(reconnect_handler)
```

Notify user when the headset is not worn properly
```python linenums="1"
... # headset connection
def signal_quality_handler(event:SignalQualityEvent):
if event.signal_quality < 100:
print("Please wear the headset properly")

subscription = headset.on_signal_quality_change(signal_quality_handler)
```
---
Subscribe to session signals, such as start and end of each trial and phases of the trial. This can be used to build a GUI on top of it to create data collection environment.
```python linenums="1"
... # session and headset connection
def session_handler(event:SessionEvent):
signal = event.signal
if signal == SessionSignal.SESSION_START:
print("Session started")
elif signal == SessionSignal.TRIAL_START:
print("Trial started for class:", event.class_name)
elif signal == SessionSignal.REST:
print("Resting phase")
elif signal == SessionSignal.READY:
print("Ready for the motor imagery task")
elif signal == SessionSignal.CUE:
print("Cue for the motor imagery task")
elif signal == SessionSignal.MOTOR :
print("Motor imagery task")
elif signal == SessionSignal.TRIAL_END:
print("Trial ended")
elif signal == SessionSignal.SESSION_END:
print("Session ended")

subscription = session.on_signal(session_handler)
```
for the full list of Session Signals, check [SessionSignal](https://princeegy.github.io/pymindwave2/api/enums/#mindwave.session.SessionSignal)

for the data collection session workflow, check [Session Workflow](https://princeegy.github.io/pymindwave2/api/session/#mindwave.session.Session)
5 changes: 5 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{%
include-markdown "../README.md"
start='<!-- Intro -->'
end='<!-- Installation -->'
%}
5 changes: 5 additions & 0 deletions docs/installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{%
include-markdown "../README.md"
start='<!-- Installation -->'
end='<!-- Usage -->'
%}
5 changes: 5 additions & 0 deletions docs/quickstart.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{%
include-markdown "../README.md"
start='<!-- Usage -->'
end='<!-- Contributing -->'
%}
67 changes: 67 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
site_name: PyMindWave2 Docs
repo_url: https://github.com/PrinceEGY/pymindwave2
repo_name: PrinceEGY/pymindwave2

theme:
name: material
features:
- toc.title
- search.suggest
- search.highlight
- content.tabs.link
- content.tabs.annotation
- content.code.copy
language: en

plugins:
- search
- mkdocstrings:
handlers:
python:
import:
- https://docs.python.org/3/objects.inv

options:
docstring_style: google
members_order: source
merge_init_into_class: true
show_root_heading: true
show_root_full_path: false
show_symbol_type_heading: true
show_symbol_type_toc: true
separate_signature: true
signature_crossrefs: true
show_signature_annotations: true
docstring_options:
ignore_init_summary: true

- include-markdown

nav:
- Home: index.md
- Installation: installation.md
- Quick Start: quickstart.md
- Examples: examples.md
- API Documentaion:
- MindwaveMobile2: api/headset.md
- Session: api/session.md
- Events: api/events.md
- Enums: api/enums.md
- ThinkGear Connector: api/tg_connector.md

markdown_extensions:
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
- admonition
- pymdownx.arithmatex:
generic: true
- footnotes
- pymdownx.details
- pymdownx.superfences
- pymdownx.mark
- attr_list

copyright: |
&copy; 2024 <a href="https://github.com/PrinceEGY/" target="_blank" rel="noopener">PrinceEGY</a>

0 comments on commit 1377088

Please sign in to comment.