doc updates

mostly spell checking
some sphinx config changes

Author: 2bndy5

.cspell.config.yml

@@ -5,31 +5,53 @@ words:
   - addopts
   - armv
   - ATSAMD
+  - autoattribute
+  - autoclass
+  - autofunction
+  - automethod
+  - automodule
+  - autoproperty
   - baudrate
+  - bgcolor
   - blinka
   - busdevice
   - busio
+  - bysource
+  - bytearray
   - capsys
+  - CELLBORDER
+  - CELLSPACING
   - CIRCUITPY
   - circuitpython
+  - coef
   - datasheet
+  - dhcplist
   - digitalio
   - Disabl
   - Dmitry
+  - docstitle
   - Doherty
   - Eddystone
   - elif
   - Fals
+  - fontcolor
+  - fontname
+  - fontsize
+  - graphviz
   - Grinberg
   - hexlified
   - HHHBB
   - Hinch
+  - intersphinx
+  - isascii
   - Itsy
   - Kbps
+  - labelloc
   - LENG
   - levelname
   - Mbps
   - microcontroller
+  - microcontrollers
   - micropython
   - minversion
   - MOSI
@@ -38,16 +60,29 @@ words:
   - multicasts
   - multiceiver
   - mypy
+  - newrank
+  - penwidth
   - Pinout
+  - Pluss
   - pytest
+  - ranksep
   - raspberrypi
+  - repr
+  - rgba
   - Rhys
+  - Roboto
   - seealso
+  - setlinewidth
   - setuptools
+  - sparkfun
   - spidev
   - testpaths
   - toctree
+  - twopi
   - urandom
   - venv
   - versionadded
+  - versionchanged
+  - viewcode
+  - WLAN
   - xfer

docs/conf.py

@@ -121,12 +121,9 @@
 
 html_theme_options = {
     "features": [
-        # "navigation.expand",
         "navigation.tabs",
-        # "toc.integrate",
         "navigation.sections",
         "navigation.instant",
-        # "header.autohide",
         "navigation.top",
         # "search.highlight",
         "search.share",
@@ -163,6 +160,13 @@
         },
     ],
     "palette": [
+        {
+            "media": "(prefers-color-scheme)",
+            "toggle": {
+                "icon": "material/brightness-auto",
+                "name": "Switch to dark mode",
+            },
+        },
         {
             "media": "(prefers-color-scheme: dark)",
             "scheme": "slate",
@@ -188,8 +192,6 @@
     "site_url": html_baseurl,
     "repo_url": "https://github.com/nRF24/CircuitPython_nRF24L01/",
     "repo_name": "CircuitPython_nRF24L01",
-    # If False, expand all TOC entries
-    "globaltoc_collapse": False,
     "toc_title_is_page_title": True,
 }
 
@@ -262,6 +264,3 @@
 
 # project logo
 html_logo = "_static/Logo large.png"
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = "nRF24L01_Library_doc"

docs/core_api/advanced_api.rst

@@ -286,7 +286,7 @@ Debugging Output
 
     :param buf: The buffer of bytes to convert into a hexlified
         string.
-    :param reverse: A `bool` to control the resulting endianess. `True`
+    :param reverse: A `bool` to control the resulting endianness. `True`
         outputs the result as big endian. `False` outputs the result as little
         endian. This parameter defaults to `True` since `bytearray` and `bytes`
         objects are stored in big endian but written in little endian.
@@ -416,8 +416,7 @@ Status Byte
         is an antiquated status flag (after you've dealt with the specific payload related to
         the status flags that were set), otherwise it can cause payloads to be ignored and
         occupy the RX/TX FIFO buffers. See `Appendix A of the nRF24L01+ Specifications Sheet
-        <https://www.sparkfun.com/datasheets/Components/SMD/
-        nRF24L01Pluss_Preliminary_Product_Specification_v1_0.pdf#G1047965>`_ for an outline of
+        <https://www.sparkfun.com/datasheets/Components/SMD/nRF24L01Pluss_Preliminary_Product_Specification_v1_0.pdf#G1047965>`_ for an outline of
         proper behavior.
 
 

docs/core_api/ble_api.rst

@@ -128,7 +128,7 @@ here has been adapted to work with CircuitPython.
 .. autofunction:: circuitpython_nrf24l01.fake_ble.whitener
 
     This is a helper function to `FakeBLE.whiten()`. It has been broken out of the
-    `FakeBLE` class to allow whitening and dewhitening a BLE payload without the
+    `FakeBLE` class to allow whitening and de-whitening a BLE payload without the
     hardcoded coefficient.
 
     :param buf: The BLE payloads data. This data should include the
@@ -220,7 +220,7 @@ FakeBLE class
 
     .. versionchanged:: 2.1.0 Invalid input ignored
 
-        Prevoiusly, any invalid input value (that is not found in `BLE_FREQ`) had raised a
+        Previously, any invalid input value (that is not found in `BLE_FREQ`) had raised a
         `ValueError` exception. This behavior changed to ignoring invalid input values,
         and the exception is no longer raised.
 

docs/troubleshooting.rst

@@ -157,7 +157,7 @@ version:
 * :attr:`~circuitpython_nrf24l01.rf24.RF24.pa_level` is available, but it will not accept a `list` or `tuple`.
 * `start_carrier_wave()`, & `stop_carrier_wave()` removed. These only perform a
   test of the nRF24L01's hardware. `rpd` is still available.
-* All comments and docstrings removed, meaning ``help()`` will not provide any specific
+* All comments and doc comments removed, meaning ``help()`` will not provide any specific
   information. Exception prompts have also been reduced and adjusted accordingly.
 * Cannot switch between different radio configurations using context manager (the `with`
   blocks). It is advised that only one `RF24` object be instantiated when RAM is limited

tests/test_fake_ble.py

@@ -35,7 +35,7 @@ def test_lvl_mask(lvl: int, expected: int):
 
 
 def test_whitener(ble_obj: FakeBLE):
-    """test whitening and dewhitening an arbitrary buffer."""
+    """test whitening and de-whitening an arbitrary buffer."""
     buf = os.urandom(24)
     for freq in range(3):
         coef = (freq + 37) | 0x40
@@ -65,7 +65,7 @@ def test_rev_bits():
 def test_ble_mac(ble_obj: FakeBLE, addr: Optional[Union[int, bytes]]):
     """test the FakeBLE mac attribute."""
     assert isinstance(ble_obj.mac, (bytes, bytearray))
-    ble_obj.mac = addr
+    ble_obj.mac = addr  # type: ignore[assignment]
     assert ble_obj.mac is not None and len(ble_obj.mac) == 6
     if addr is not None:
         if isinstance(addr, int):
@@ -86,7 +86,7 @@ def test_ble_mac(ble_obj: FakeBLE, addr: Optional[Union[int, bytes]]):
 )
 def test_name(ble_obj: FakeBLE, name: Optional[Union[str, bytes, int]]):
     """test FakeBLE name attribute."""
-    ble_obj.name = name
+    ble_obj.name = name  # type: ignore[assignment]
     if isinstance(name, str):
         assert name.encode(encoding="utf-8") == ble_obj.name
     else:
@@ -103,7 +103,7 @@ def test_name(ble_obj: FakeBLE, name: Optional[Union[str, bytes, int]]):
 def test_show_pa_level(ble_obj: FakeBLE, name: Optional[Union[str, bytes, int]]):
     """test FakeBLE show_pa_level attribute."""
     assert not ble_obj.show_pa_level
-    ble_obj.name = name
+    ble_obj.name = name  # type: ignore[assignment]
     ble_obj.show_pa_level = True
     assert ble_obj.show_pa_level
 
@@ -169,11 +169,12 @@ def inject_rx_payload(ble_obj: FakeBLE, monkeypatch: pytest.MonkeyPatch):
     return repr(service_data)
 
 
-def test_rx_payload(ble_obj: FakeBLE, inject_rx_payload: pytest.fixture):
+def test_rx_payload(ble_obj: FakeBLE, inject_rx_payload: pytest.fixture):  # type: ignore
     """test available() and read()"""
     buf_repr = inject_rx_payload
     assert ble_obj.available()
     payload = ble_obj.read()
+    assert payload
     assert payload.mac == ble_obj.mac
     assert payload.name == "test"
     assert not payload.pa_level

tests/test_rf24.py

@@ -1,8 +1,8 @@
 """Test functions related to core RF24 functionality."""
 
-from typing import Optional
+from typing import Optional, Union
 import pytest
-from circuitpython_nrf24l01.rf24 import RF24
+from circuitpython_nrf24l01.rf24 import RF24, FIFO_EMPTY, FIFO_FULL, FIFO_OCCUPIED
 from circuitpython_nrf24l01.fake_ble import FakeBLE
 
 
@@ -299,3 +299,49 @@ def test_carrier_functions(rf24_obj: RF24, monkeypatch: pytest.MonkeyPatch):
     assert not rf24_obj.power
     assert not rf24_obj.ce_pin
     assert not rf24_obj._spi._spi.state.registers[6][0] & 0x90
+
+
+@pytest.mark.parametrize(
+    "reg_val,expected,about_tx,check_empty",
+    [
+        # raw RX state
+        (0x1, FIFO_EMPTY, False, None),
+        (0x2, FIFO_FULL, False, None),
+        (0, FIFO_OCCUPIED, False, None),
+        # raw TX state
+        (0x10, FIFO_EMPTY, True, None),
+        (0x20, FIFO_FULL, True, None),
+        (0, FIFO_OCCUPIED, True, None),
+        # simplified RX state
+        (0x1, bool(FIFO_EMPTY), False, True),  # is empty
+        (0x2, bool(FIFO_FULL), False, False),  # is full
+        # simplified TX state
+        (0x10, bool(FIFO_EMPTY), True, True),  # is empty
+        (0x20, bool(FIFO_FULL), True, False),  # is full
+        # simulated binary corrupted MISO
+        pytest.param(3, 3, False, None, marks=pytest.mark.xfail),
+    ],
+    ids=[
+        "RX_EMPTY",
+        "RX_FULL",
+        "RX_OCCUPIED",
+        "TX_EMPTY",
+        "TX_FULL",
+        "TX_OCCUPIED",
+        "bool(RX_EMPTY)",
+        "bool(RX_FULL)",
+        "bool(TX_EMPTY)",
+        "bool(TX_FULL)",
+        "bin-corruption",
+    ],
+)
+def test_fifo_state(
+    rf24_obj,
+    reg_val: int,
+    expected: Union[int, bool],
+    about_tx: bool,
+    check_empty: Optional[bool],
+):
+    """check the fifo state is accurately described"""
+    rf24_obj._spi._spi.state.registers[0x17][0] = reg_val
+    assert expected == rf24_obj.fifo(about_tx=about_tx, check_empty=check_empty)