update documentation

doc/api/index.rst

@@ -9,14 +9,17 @@ This is the reference for classes (``CamelCase`` names) and functions
     :hidden:
 
     audio.rst
-    trigger.rst
+    keyboard.rst
     time.rst
+    trigger.rst
     utilities.rst
 
 .. include:: audio.rst
 
-.. include:: trigger.rst
+.. include:: keyboard.rst
 
 .. include:: time.rst
 
+.. include:: trigger.rst
+
 .. include:: utilities.rst

doc/api/keyboard.rst

@@ -0,0 +1,32 @@
+.. include:: ../links.inc
+
+Keyboard
+--------
+
+To interact with the keyboard during an experiment, you can use a
+:class:`~stimuli.keyboard.Keyboard` object which monitors in a separate thread for key
+inputs.
+
+.. curentmodule:: stimuli.keyboard
+
+.. autosummary::
+    :toctree: ../generated/api
+
+    Keyboard
+    KeyEvent
+
+Example usage::
+
+    from stimuli.keyboard import Keyboard
+    from stimuli.time import sleep
+
+
+    kb = Keyboard(keys=["esc", "space"]).start(suppress=True)
+    while True:
+        events = kb.get_keys()
+        if any(event.key == "esc" for event in events):
+            print("Escape key pressed")
+            break
+        spaces = [event.key == "space" for event in events]
+        print(f"Space bar pressed {spaces.count(True)} times in the last 500 ms.")
+        sleep(0.5)

doc/conf.py

@@ -132,6 +132,7 @@
         "sounddevice",
     }
 )
+intersphinx_mapping["pynput"] = ("https://pynput.readthedocs.io/en/stable/", None)
 intersphinx_timeout = 5
 
 # -- sphinx-issues -----------------------------------------------------------