docs: add source documentation

Author: qlrd

.gitignore

@@ -86,3 +86,6 @@ krux-*/ktool*
 
 # IDE files
 .vscode
+
+# Readthedocs
+docs/_static/*

docs/conf.py

@@ -2,85 +2,82 @@
 #
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
+
 import os
 import sys
 import time as _time
-from mock import Mock as MagicMock
+from unittest.mock import MagicMock
 
 
-class DictMock(MagicMock):
-    """Mock that supports dictionary-like behavior."""
+class HashableMock:
+    """A simple hashable mock that can be used as dictionary keys."""
 
-    def __getitem__(self, key):
-        return self.__dict__.setdefault(key, DictMock())
+    _counter = 0
 
-    def __setitem__(self, key, value):
-        self.__dict__[key] = value
+    def __init__(self, name="mock"):
+        HashableMock._counter += 1
+        self._name = name
+        self._id = HashableMock._counter
 
-    def __iter__(self):
-        return iter([])
+    def __hash__(self):
+        return self._id
 
-    def __contains__(self, key):
+    def __eq__(self, other):
+        if isinstance(other, HashableMock):
+            return self._id == other._id
         return False
 
-    def get(self, key, default=None):
-        return self.__dict__.get(key, default)
-
-    # Support arithmetic operations
-    def __sub__(self, other):
-        return 0
-
-    def __rsub__(self, other):
-        return 0
+    def __repr__(self):
+        return f"<HashableMock {self._name}>"
 
-    def __add__(self, other):
-        return 0
-
-    def __radd__(self, other):
-        return 0
-
-    def __mul__(self, other):
-        return 0
+    def __call__(self, *args, **kwargs):
+        return HashableMock(self._name)
 
-    def __rmul__(self, other):
-        return 0
+    def __getattr__(self, name):
+        return HashableMock(f"{self._name}.{name}")
 
-    def __truediv__(self, other):
+    def __int__(self):
         return 0
 
-    def __rtruediv__(self, other):
-        return 0
+    def __bool__(self):
+        return False
 
-    def __floordiv__(self, other):
-        return 0
 
-    def __rfloordiv__(self, other):
-        return 0
+class MockModule(MagicMock):
+    """Mock module that returns HashableMock for attributes that might be used as dict keys."""
 
-    def __int__(self):
-        return 0
+    # Attributes known to be used as dict keys
+    HASHABLE_ATTRS = {
+        "MODE_AES",
+        "MODE_CTR",
+        "MODE_CBC",
+        "MODE_ECB",
+        "AES",
+        "CTR",
+        "CBC",
+        "ECB",
+    }
 
-    def __float__(self):
-        return 0
+    def __getattr__(self, name):
+        if name in self.HASHABLE_ATTRS or name.startswith("MODE_"):
+            return HashableMock(name)
+        return MagicMock()
 
-    def __bool__(self):
-        return False
 
-    def __len__(self):
-        return 0
+class MockWordlist:
+    """Mock for embit.wordlists.bip39.WORDLIST - returns list of strings."""
 
-    def __call__(self, *args, **kwargs):
-        return DictMock()
+    WORDLIST = ["abandon"] * 2048  # Dummy wordlist
 
 
 class MockTime:
     """Mock time module with MicroPython-specific functions."""
 
-    # Preserve all standard time functions
     def __getattr__(self, name):
-        return getattr(_time, name)
+        if hasattr(_time, name):
+            return getattr(_time, name)
+        return MagicMock()
 
-    # Add MicroPython-specific functions
     @staticmethod
     def ticks_ms():
         return 0
@@ -91,11 +88,11 @@ def ticks_us():
 
     @staticmethod
     def ticks_diff(a, b):
-        return a - b
+        return 0
 
     @staticmethod
     def ticks_add(a, b):
-        return a + b
+        return 0
 
     @staticmethod
     def sleep_ms(ms):
@@ -106,110 +103,119 @@ def sleep_us(us):
         pass
 
 
-# Create mock for board with required config structure
-MOCK_BOARD = DictMock()
-MOCK_BOARD.config = MOCK_BOARD.config = {
-    "type": "amigo",
-    "lcd": {"height": 320, "width": 480, "invert": 0, "dir": 40, "lcd_type": 1},
-    "sdcard": {"sclk": 11, "mosi": 10, "miso": 6, "cs": 26},
-    "board_info": {
-        "BOOT_KEY": 23,
-        "CONNEXT_A": 7,
-        "CONNEXT_B": 9,
-        "LED_R": 14,
-        "LED_G": 15,
-        "LED_B": 17,
-        "LED_W": 32,
-        "BACK": 23,
-        "ENTER": 16,
-        "NEXT": 20,
-        "WIFI_TX": 6,
-        "WIFI_RX": 7,
-        "WIFI_EN": 8,
-        "I2S0_MCLK": 13,
-        "I2S0_SCLK": 21,
-        "I2S0_WS": 18,
-        "I2S0_IN_D0": 35,
-        "I2S0_OUT_D2": 34,
-        "I2C_SDA": 27,
-        "I2C_SCL": 24,
-        "SPI_SCLK": 11,
-        "SPI_MOSI": 10,
-        "SPI_MISO": 6,
-        "SPI_CS": 12,
-    },
-    "krux": {
-        "pins": {
-            "BUTTON_A": 16,
-            "BUTTON_B": 20,
-            "BUTTON_C": 23,
-            "TOUCH_IRQ": 33,
+class MockBoard:
+    """Mock board module with config structure."""
+
+    config = {
+        "type": "amigo",
+        "lcd": {"height": 320, "width": 480, "invert": 0, "dir": 40, "lcd_type": 1},
+        "sdcard": {"sclk": 11, "mosi": 10, "miso": 6, "cs": 26},
+        "board_info": {
+            "BOOT_KEY": 23,
+            "CONNEXT_A": 7,
+            "CONNEXT_B": 9,
+            "LED_R": 14,
+            "LED_G": 15,
+            "LED_B": 17,
             "LED_W": 32,
+            "BACK": 23,
+            "ENTER": 16,
+            "NEXT": 20,
+            "WIFI_TX": 6,
+            "WIFI_RX": 7,
+            "WIFI_EN": 8,
             "I2C_SDA": 27,
             "I2C_SCL": 24,
         },
-        "display": {"touch": True, "font": [12, 24], "font_wide": [24, 24]},
-    },
-}
-
-MOCK_TIME = MockTime()
+        "krux": {
+            "pins": {
+                "BUTTON_A": 16,
+                "BUTTON_B": 20,
+                "BUTTON_C": 23,
+                "TOUCH_IRQ": 33,
+                "LED_W": 32,
+                "I2C_SDA": 27,
+                "I2C_SCL": 24,
+            },
+            "display": {"touch": True, "font": [12, 24], "font_wide": [24, 24]},
+        },
+    }
 
+    def __getattr__(self, name):
+        return MagicMock()
 
-def ignore_modules(*args):
-    for mod_name in list(args):
-        if mod_name == "board":
-            sys.modules[mod_name] = MOCK_BOARD
-        elif mod_name == "time":
-            sys.modules[mod_name] = MOCK_TIME
-        else:
-            sys.modules[mod_name] = DictMock()
-
-
-# Mock ALL MicroPython and hardware-dependent modules
-ignore_modules(
-    # MicroPython built-ins
-    "machine",
-    "board",
-    "pmu",
-    "time",
-    "lcd",
-    "ujson",
-    "urandom",
-    "ucryptolib",
-    "uhashlib",
-    "uctypes",
-    "uos",
-    "usys",
-    "gc",
-    # K210/Maix specific
-    "Maix",
-    "fpioa_manager",
-    "sensor",
-    "image",
-    "flash",
-    # Crypto
-    "secp256k1",
-    "qrcode",
-    # Scientific (if used)
-    "numpy",
-    "scipy",
-    "scipy. linalg",
-    "scipy.signal",
-)
 
+# Create mock instances
+MOCK_TIME = MockTime()
+MOCK_BOARD = MockBoard()
+MOCK_UCRYPTOLIB = MockModule()
+MOCK_UCRYPTOLIB.aes = MockModule()
+
+# Mock for embit.wordlists.bip39
+MOCK_BIP39 = type("MockBip39", (), {"WORDLIST": ["abandon"] * 2048})()
+
+
+def setup_mocks():
+    """Setup all mocked modules."""
+
+    mocks = {
+        # MicroPython built-ins
+        "machine": MagicMock(),
+        "board": MOCK_BOARD,
+        "pmu": MagicMock(),
+        "time": MOCK_TIME,
+        "lcd": MagicMock(),
+        "ujson": MagicMock(),
+        "urandom": MagicMock(),
+        "ucryptolib": MOCK_UCRYPTOLIB,
+        "uhashlib": MagicMock(),
+        "uhashlib_hw": MagicMock(),
+        "uctypes": MagicMock(),
+        "uos": MagicMock(),
+        "usys": MagicMock(),
+        "gc": MagicMock(),
+        # K210/Maix specific
+        "Maix": MagicMock(),
+        "fpioa_manager": MagicMock(),
+        "sensor": MagicMock(),
+        "image": MagicMock(),
+        "flash": MagicMock(),
+        # Crypto/QR
+        "secp256k1": MagicMock(),
+        "qrcode": MagicMock(),
+        # Embit (Bitcoin library)
+        "embit": MagicMock(),
+        "embit.wordlists": MagicMock(),
+        "embit.wordlists.bip39": MOCK_BIP39,
+        "embit.psbt": MagicMock(),
+        "embit.networks": MagicMock(),
+        "embit.descriptor": MagicMock(),
+        "embit.descriptor.descriptor": MagicMock(),
+        "embit.descriptor.arguments": MagicMock(),
+        # Scientific (if needed)
+        "numpy": MagicMock(),
+        "scipy": MagicMock(),
+        "scipy.linalg": MagicMock(),
+        "scipy.signal": MagicMock(),
+    }
+
+    for mod_name, mock_obj in mocks.items():
+        sys.modules[mod_name] = mock_obj
+
+
+# Setup mocks before importing anything
+setup_mocks()
+
+# Add source path
 sys.path.insert(0, os.path.abspath("../src/"))
 
 # -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
 project = "Krux"
 copyright = "2022, MIT"
 author = "Selfcustody"
 release = "2022"
 
 # -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.coverage",
@@ -224,9 +230,23 @@ def ignore_modules(*args):
 templates_path = ["_templates"]
 exclude_patterns = []
 
+# Suppress duplicate object warnings
+suppress_warnings = ["autodoc", "autodoc.import_object"]
 
 # -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-
 html_theme = "sphinx_rtd_theme"
-html_static_path = ["_static"]
+html_static_path = []  # Remove _static to avoid warning
+
+# Suppress warnings
+suppress_warnings = ["autodoc"]
+
+
+def skip_mock_members(app, what, name, obj, skip, options):
+    """Skip mock objects that can't be documented."""
+    if "Mock" in str(type(obj)):
+        return True
+    return skip
+
+
+def setup(app):
+    app.connect("autodoc-skip-member", skip_mock_members)