feat(docs): Add sphinx documentation

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

.gitignore

 build/
-card10.bin
+/Documentation/output/
+__pycache__/

Documentation/build-docs.sh

+#!/bin/bash
+set -e
+
+cd "$(dirname "$0")"
+
+sphinx-build -b html . ./output

Documentation/conf.py

+import os
+import subprocess
+import sys
+import time
+import sphinx.util.logging
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+sys.path.insert(0, os.path.abspath("../pycardium/modules/py"))
+
+logger = sphinx.util.logging.getLogger("card10/conf.py")
+
+
+# -- Project information -----------------------------------------------------
+
+project = "card10-firmware"
+copyright = "2019"
+
+# The full version, including alpha/beta/rc tags
+release = subprocess.check_output(
+    ["git", "describe", "--long", "--always"]
+).decode().strip()
+release += "<br />"
+release += time.strftime("%F %R")
+version = release
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.ifconfig",
+]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["output", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output ------------------------------------------------- {{{
+
+# The Read the Docs theme is available from
+# - https://github.com/snide/sphinx_rtd_theme
+# - https://pypi.python.org/pypi/sphinx_rtd_theme
+# - python-sphinx-rtd-theme package (on Debian)
+try:
+    import sphinx_rtd_theme
+    html_theme = "sphinx_rtd_theme"
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+    pygments_style = "monokai"
+except ImportError:
+    logger.warning("The Sphinx \"sphinx_rtd_theme\" HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme.")
+
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["static"]
+# }}}
+
+# -- Options for Auto-Doc ---------------------------------------------------- {{{
+autodoc_mock_imports = [
+    "ucollections",
+    "urandom",
+    "utime",
+]
+
+autodoc_member_order = "bysource"
+# }}}
+
+# -- Options for Hawkmoth ---------------------------------------------------- {{{
+has_hawkmoth = False
+try:
+    # Attempt importing hawkmoth
+    import hawkmoth  # noqa: F401
+    extensions.append("hawkmoth")
+
+    cautodoc_root = os.path.abspath("..")
+    has_hawkmoth = True
+except ImportError:
+    logger.warning("Hawkmoth was not found.  Documentation for Epicardium API will not be generated.")
+# }}}
+
+
+# -- Sphinx Setup ------------------------------------------------------------
+def setup(app):
+    app.add_config_value("has_hawkmoth", has_hawkmoth, "")

Documentation/epicardium.rst

+Epicardium
+==========
+
+Epicardium is the main firmware.  It runs on core0 and is based on FreeRTOS.
+Epicardium provides an API to a payload running on the other core which exposes
+most functionality.  This section of the docs details this "Epicardium API".
+
+.. toctree::
+   :maxdepth: 1
+
+   epicardium/api

Documentation/epicardium/api.rst

+Epicardium API
+==============
+
+.. ifconfig:: not has_hawkmoth
+
+   .. warning::
+
+      This version of the documentation was built without
+      `Hawkmoth <https://github.com/jnikula/hawkmoth>`_ available.  This means,
+      no documentation for the Epicardium API was generated.
+
+.. c:autodoc:: epicardium/epicardium.h

Documentation/index.rst

+card10 firmware docs
+====================
+
+This is the API documentation for card10's default firmware.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   epicardium
+   pycardium

Documentation/pycardium.rst

+Pycardium
+=========
+
+Pycardium is a core1 payload based on MicroPython.  It can interface with
+card10 using the Epicardium API, which is wrapped in a bunch of python modules.
+These modules are documented in this section.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Modules:
+
+   pycardium/color
+   pycardium/leds

Documentation/pycardium/color.rst

+``color`` - Colors
+==================
+
+Color Class
+-----------
+
+.. automodule:: color
+   :members:
+
+Constants
+---------
+
+The color module also contains a few constanst for commonly used colors:
+
+.. py:data:: color.BLACK
+.. py:data:: color.WHITE
+.. py:data:: color.RED
+.. py:data:: color.GREEN
+.. py:data:: color.YELLOW
+.. py:data:: color.BLUE
+.. py:data:: color.MAGENTA
+.. py:data:: color.CYAN

Documentation/pycardium/leds.rst

+``leds`` - LEDs
+===============
+
+.. py:function:: leds.set(led, color)
+
+   Set one of the card10's RGB LEDs to a certain color::
+
+      import leds, color
+
+      for i in range(11):
+         leds.set(i, color.RED)
+
+   :param led:  Which led to set.  0-10 are the leds on the top and 11-14 are the 4 "ambient" leds.
+   :param color:  What color to set the led to.  Should be a :py:class:`color.Color` but any list/tuple
+      with 3 elements will work just as well.
+
+.. py:data:: leds.BOTTOM_RIGHT
+
+   Index of the LED in the bottom right of card10.
+
+.. py:data:: leds.BOTTOM_LEFT
+
+   Index of the LED in the bottom left of card10.
+
+.. py:data:: leds.TOP_RIGHT
+
+   Index of the LED in the top right of card10.
+
+.. py:data:: leds.TOP_LEFT
+
+   Index of the LED in the top left of card10.

epicardium/epicardium.h

@@ -6,13 +6,51 @@
 #define API(id, def) def
 #endif
 
-#define API_UART_WRITE 0x1
+/* clang-format off */
+#define API_UART_WRITE         0x1
+#define API_UART_READ          0x2
+#define API_LEDS_SET           0x3
+/* clang-format on */
+
+/**
+ * UART/Serial Interface
+ * =====================
+ */
+
+/**
+ * Write a string to all connected serial devices.  This includes:
+ *
+ * - Real UART, whose pins are mapped onto USB-C pins.  Accessible via the HW-debugger.
+ * - A CDC-ACM device available via USB.
+ * - Maybe, in the future, bluetooth serial?
+ *
+ * :param str:  String to write.  Does not necessarily have to be NULL-terminated.
+ * :param length:  Amount of bytes to print.
+ */
 API(API_UART_WRITE, void epic_uart_write_str(const char *str, intptr_t length));
 
-#define API_UART_READ 0x2
+/**
+ * Blocking read a single character from any connected serial device.
+ * ``epic_uart_read_chr`` only returns
+ * once one byte has been read.
+ *
+ * :return:  The byte.
+ */
 API(API_UART_READ, char epic_uart_read_chr(void));
 
-#define API_LEDS_SET 0x3
+/**
+ * LEDs
+ * ====
+ */
+
+/**
+ * Set one of card10's RGB LEDs to a certain color.
+ *
+ * :param led:  Which led to set.  0-10 are the leds on the top and 11-14 are the 4 "ambient" leds.
+ * :param r:  Red component of the color.
+ * :param g:  Green component of the color.
+ * :param b:  Blue component of the color.
+ */
 API(API_LEDS_SET, void epic_leds_set(int led, uint8_t r, uint8_t g, uint8_t b));
 
 #endif /* _EPICARDIUM_H */

pycardium/modules/py/color.py

@@ -4,8 +4,39 @@ _ColorTuple = ucollections.namedtuple("Color", ["red", "green", "blue"])
 
 
 class Color(_ColorTuple):
+    """
+    A color in 24-bit RGB.
+
+    You can create a new color from red, green, and blue::
+
+        yellow = Color(255, 255, 0)
+
+    You can get the HTML representation for a color using::
+
+        html_repr = str(Color(128, 128, 128))
+        assert html_repr == "#808080"
+
+    .. py:attribute:: red
+
+        Red component of this color.
+
+    .. py:attribute:: green
+
+        Green component of this color.
+
+    .. py:attribute:: blue
+
+        Blue component of this color.
+    """
+
     @classmethod
     def from_hex(cls, color):
+        """
+        Create a color from a hexadecimal number::
+
+            # Magenta
+            Color.from_hex(0xff00ff)
+        """
         red = (color & 0xff0000) >> 16
         green = (color & 0x00ff00) >> 8
         blue = (color & 0x0000ff)