docs: Document buttons module

Signed-off-by: Rahix <rahix@rahix.de>

Documentation/index.rst

@@ -21,6 +21,7 @@ Last but not least, if you want to start hacking the lower-level firmware, the
    :caption: Pycardium
 
    pycardium/overview
+   pycardium/buttons
    pycardium/color
    pycardium/display
    pycardium/leds

Documentation/pycardium/buttons.rst

+.. py:module:: buttons
+
+``buttons`` - Push Buttons
+==========================
+The :py:mod:`buttons` module allows you to use card10's push buttons as input
+in your scripts.
+
+**Example**:
+
+.. code-block:: python
+
+   import buttons
+
+   print("Press bottom left or right button:")
+
+   while True:
+      pressed = buttons.read(
+          buttons.BOTTOM_LEFT | buttons.BOTTOM_RIGHT
+      )
+
+      if pressed != 0:
+         break
+
+   if pressed & buttons.BOTTOM_LEFT != 0:
+      print("Left button pressed!")
+
+   if pressed & buttons.BOTTOM_RIGHT != 0:
+      print("Left button pressed!")
+
+.. py:function:: buttons.read(mask)
+
+   Read button status.
+
+   :param int mask: Mask of buttons to check.  Create the mask by ORing :py:data:`buttons.BOTTOM_LEFT`, :py:data:`buttons.BOTTOM_RIGHT`, :py:data:`buttons.TOP_RIGHT`, and :py:data:`buttons.TOP_LEFT` (= :py:data:`buttons.RESET`).
+   :returns: An integer with the bits for pressed buttons set.  Use the same
+      costants as for the mask to check which buttons were pressed.
+
+.. py:data:: buttons.BOTTOM_LEFT
+
+   Bottom left button.
+
+.. py:data:: buttons.BOTTOM_RIGHT
+
+   Bottom right button.
+
+.. py:data:: buttons.TOP_RIGHT
+
+   Top right button.
+
+.. py:data:: buttons.TOP_LEFT
+
+   Top left button (Reset button).
+
+.. py:data:: buttons.RESET
+
+   Top left button (Reset button).