Improve docs, add mkdocs & readthedocs config (#32)

* Improve docs and fix formatting

* Add mkdocs documentation

* Add readthedocs config

Author: bofh69

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: false
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

Makefile

@@ -41,13 +41,25 @@ $(VENV)/.timestamp-dev: $(VENV)/bin/activate pyproject.toml
 	$(PIP) install -e ".[dev]"
 	touch $@
 
+# Install package with docs dependencies
+$(VENV)/.timestamp-docs: $(VENV)/bin/activate pyproject.toml
+	$(PIP) install -e ".[docs]"
+	touch $@
+
 .PHONY: install-dev
 install-dev: $(VENV)/.timestamp-dev
 
+.PHONY: install-docs
+install-dev: $(VENV)/.timestamp-docs
+
 .PHONY: test
 test: install-dev
 	$(PYTEST)
 
+.PHONY: docs
+docs: install-docs
+	mkdocs build
+
 .PHONY: lint
 lint: install-dev
 	$(RUFF) check src/ tests/
@@ -66,6 +78,7 @@ clean:
 	rm -rf $(VENV)
 	rm -rf build/
 	rm -rf dist/
+	rm -rf site/
 	rm -rf *.egg-info
 	rm -rf .pytest_cache
 	rm -rf .ruff_cache

README.md

@@ -22,12 +22,14 @@ Frontend module and a Raspberry Pi Pico (Zero).
 - Python library for easy integration.
 - Uses USB serial communication to the reader.
 - Cross-platform support (Linux, Windows, macOS).
-- Finds and selects single ISO/IEC 14443 cards.
-- Uses NFC FORUM commands to read/write 14443-A cards' memories.
+- Finds and selects ISO/IEC 14443A and ISO/IEC 15693 cards.
+- Can read/write the cards' memories.
 - Can authenticate against Mifare classic cards to read their memories.
-- Finds ISO/IEC 15693 cards, uses 15693-3 commands to read/write their memories.
+- Supports multiple cards within the field.
 
-Multiple cards can be detected within the field.
+## API Documentation
+
+See [API Reference](https://pn5180-tagomatic.readthedocs.io/en/latest/).
 
 ## Installation
 

REUSE.toml

@@ -13,7 +13,12 @@ SPDX-FileCopyrightText = "2026 PN5180-tagomatic contributors"
 SPDX-License-Identifier = "GPL-3.0-or-later"
 
 [[annotations]]
-path = [".gitignore", ".clang-format"]
+path = [
+  ".gitignore",
+  ".clang-format",
+  ".readthedocs.yaml",
+  "docs/reference.md"
+]
 precedence = "aggregate"
 SPDX-FileCopyrightText = "2026 PN5180-tagomatic contributors"
 SPDX-License-Identifier = "CC0-1.0"

docs/README.md

@@ -0,0 +1,74 @@
+<!--
+SPDX-FileCopyrightText: 2026 PN5180-tagomatic contributors
+SPDX-License-Identifier: GPL-3.0-or-later
+-->
+
+# PN5180 Tagomatic
+A USB connected RFID Reader/Writer with a python interface.
+
+---
+
+A PN5180 card is connected to a Raspberry Pi Pico Zero via SPI.
+The Pico Zero runs an arduino firmware which exposes a SimpleRPC
+interface which this python module uses via USB to communicate
+with RFID tags.
+
+## Features
+
+- Python library for easy integration.
+- Uses USB serial communication to the reader.
+- Cross-platform support (Linux, Windows, macOS).
+- Finds and selects ISO/IEC 14443A and ISO/IEC 15693 cards.
+- Can read/write the cards' memories.
+- Can authenticate against Mifare classic cards to read their memories.
+- Supports multiple cards within the field.
+
+## API Documentation
+
+See [API Reference](reference.md).
+
+## Installation
+
+### Python Package
+
+Install from PyPI:
+
+```bash
+pip install pn5180-tagomatic
+```
+
+### Building the hardware
+
+See
+[here](https://github.com/bofh69/pn5180-tagomatic/tree/main/sketch/README.md)
+for instructions on the hardware and the firmware.
+
+## Usage
+
+```python
+from pn5180_tagomatic import PN5180, RxProtocol, TxProtocol
+
+# Create reader instance and use it
+with PN5180("/dev/ttyACM0") as reader:
+    versions = reader.ll.read_eeprom(0x10, 6)
+    with reader.start_session(
+        TxProtocol.ISO_14443_A_106, RxProtocol.ISO_14443_A_106
+    ) as session:
+        card = session.connect_one_iso14443a()
+        print(f"Reading from card {card.id}")
+        memory = card.read_memory()
+```
+
+## License
+
+This project is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later).
+
+## Contributing
+
+Contributions are welcome!
+
+## Acknowledgments
+
+This project uses FastLED by Daniel Garcia et al.
+
+SimpleRPC by Jeroen F.J. Laros, Chris Flesher et al is also used.

docs/reference.md

@@ -0,0 +1 @@
+::: src.pn5180_tagomatic

mkdocs.yml

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: 2026 PN5180-tagomatic contributors
+# SPDX-License-Identifier: CC0-1.0
+
+site_name: PN5180 Tagomatic
+repo_url: https://github.com/bofh69/pn5180-tagomatic
+
+theme:
+  name: "material"
+  palette:
+    scheme: slate
+
+plugins:
+  - search
+  - mkdocstrings
+
+nav:
+  - Home: 'README.md'
+  - API Reference: 'reference.md'

pyproject.toml

@@ -51,6 +51,13 @@ dev = [
     "types-pyserial>=3.5.0",
 ]
 
+docs = [
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.7.1",
+    "mkdocs-material-extensions>=1.3.1",
+    "mkdocstrings-python>=2.0.1",
+]
+
 [project.urls]
 Homepage = "https://github.com/bofh69/PN5180-tagomatic"
 Repository = "https://github.com/bofh69/PN5180-tagomatic"

src/pn5180_tagomatic/__init__.py

@@ -1,7 +1,7 @@
 # SPDX-FileCopyrightText: 2026 PN5180-tagomatic contributors
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-"""PN5180-tagomatic: USB based RFID reader with Python interface."""
+"""PN5180-tagomatic: USB connected RFID reader with Python interface."""
 
 from .cards import (
     Card,

src/pn5180_tagomatic/pn5180.py

@@ -27,16 +27,21 @@ class PN5180:
     Attributes:
         ll: Low-level PN5180 interface for direct hardware access.
 
-    Example:
-        >>> from pn5180_tagomatic import PN5180
+    Examples:
+        >>> from pn5180_tagomatic import *
         >>> with PN5180("/dev/ttyACM0") as reader:
-        ...     # High-level API (recommended)
-        ...     with reader.start_session(0x00, 0x80) as comm:
-        ...         card = comm.connect_one_iso14443a()
-        ...         memory = card.read_memory()
+        ...     # High-level API
+        ...     with reader.start_session(
+        ...         TxProtocol.ISO_14443_A_106, RxProtocol.ISO_14443_A_106
+        ...     ) as comm:
+        ...         card: Card = comm.connect_one_iso14443a()
+        ...         print(f"Found card: {card.id}")
+        ...         memory: bytes = card.read_memory()
         ...
-        ...     # Low-level access if needed
-        ...     reader.ll.write_register(addr, value)
+        ...     # Low-level access, when needed
+        ...     data: bytes = reader.ll.read_eeprom(0x12, 2)
+        ...     print("Read from EEPROM")
+        ...     print(f"Firmware version: {data[1]}.{data[0]}")
     """
 
     def __init__(self, tty: str) -> None:
@@ -66,11 +71,11 @@ def start_session(
         Raises:
             PN5180Error: If the operation fails.
 
-        Example:
+        Examples:
             >>> reader = PN5180("/dev/ttyACM0")
             >>> with reader.start_session(0x00, 0x80) as comm:
             ...     card = comm.connect_one_iso14443a()
-            ...     uid = card.uid
+            ...     uid = card.id.uid_as_bytes()
             ...     memory = card.read_memory()
         """
         self.ll.load_rf_config(tx_config, rx_config)