Add API documentation

.github/workflows/ci.yaml

@@ -80,6 +80,36 @@ jobs:
         run: make install
       - name: Check poetry configuration
         run: make check-poetry
+  lint-docs:
+    name: Check documentation
+    runs-on: ubuntu-latest
+    container: python:3.9-slim
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Install required packages
+        run: apt update && apt install -y ${REQUIRED_PACKAGES}
+      - name: Install Poetry
+        run: pip install poetry
+      - name: Create virtual environment
+        run: make install
+      - name: Check docs
+        run: make check-docs
+  build-docs:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    container: python:3.9-slim
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Install required packages
+        run: apt update && apt install -y ${REQUIRED_PACKAGES}
+      - name: Install Poetry
+        run: pip install poetry
+      - name: Create virtual environment
+        run: make install
+      - name: Build docs
+        run: make build-docs
   test:
     name: Run test suite
     runs-on: ubuntu-latest

.gitignore

@@ -1,2 +1,3 @@
 *.pyc
+_build
 dist

Makefile

@@ -14,7 +14,7 @@ update:
 	poetry update --with dev
 
 .PHONY: check
-check: check-format check-import-sorting check-poetry check-style check-typing
+check: check-format check-import-sorting check-poetry check-style check-typing check-docs
 
 .PHONY: check-format
 check-format:
@@ -36,6 +36,10 @@ check-style:
 check-typing:
 	poetry run mypy $(LINT_DIRS)
 
+.PHONY: check-docs
+check-docs:
+	poetry run rstcheck --recursive docs
+
 .PHONY: fix
 fix:
 	poetry run black $(FORMAT_DIRS)
@@ -48,3 +52,11 @@ test:
 .PHONY: generate-protobuf
 generate-protobuf:
 	protoc src/nitrokey/trussed/_bootloader/nrf52_upload/dfu/dfu-cc.proto --python_out=. --pyi_out=.
+
+.PHONY: generate-api-docs
+generate-api-docs:
+	poetry run sphinx-apidoc --separate --maxdepth 1 --tocfile index --output-dir docs/api src/nitrokey
+
+.PHONY: build-docs
+build-docs:
+	poetry run sphinx-build --fail-on-warning docs _build

docs/api/index.rst

@@ -0,0 +1,14 @@
+API Reference
+=============
+
+.. automodule:: nitrokey
+
+.. rubric:: Modules
+
+.. toctree::
+   :maxdepth: 1
+
+   nitrokey.nk3
+   nitrokey.nkpk
+   nitrokey.trussed
+   nitrokey.updates

docs/api/nitrokey.nk3.rst

@@ -0,0 +1,32 @@
+nitrokey.nk3
+============
+
+.. automodule:: nitrokey.nk3
+
+.. rubric:: Submodules
+
+.. toctree::
+   :maxdepth: 1
+
+   nitrokey.nk3.secrets_app
+   nitrokey.nk3.updates
+
+Accessing Nitrokey 3 Devices
+----------------------------
+
+.. autofunction:: nitrokey.nk3.list
+
+.. autofunction:: nitrokey.nk3.open
+
+Nitrokey 3 Objects
+------------------
+
+.. autoclass:: nitrokey.nk3.NK3
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: nitrokey.nk3.NK3Bootloader
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/nitrokey.nk3.secrets_app.rst

@@ -0,0 +1,7 @@
+nitrokey.nk3.secrets\_app
+=========================
+
+.. automodule:: nitrokey.nk3.secrets_app
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/nitrokey.nk3.updates.rst

@@ -0,0 +1,7 @@
+nitrokey.nk3.updates
+====================
+
+.. automodule:: nitrokey.nk3.updates
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/nitrokey.nkpk.rst

@@ -0,0 +1,24 @@
+nitrokey.nkpk
+=============
+
+.. automodule:: nitrokey.nkpk
+
+Accessing Nitrokey Passkey Devices
+----------------------------------
+
+.. autofunction:: nitrokey.nkpk.list
+
+.. autofunction:: nitrokey.nkpk.open
+
+Nitrokey Passkey Objects
+------------------------
+
+.. autoclass:: nitrokey.nkpk.NKPK
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: nitrokey.nkpk.NKPKBootloader
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/nitrokey.trussed.admin_app.rst

@@ -0,0 +1,7 @@
+nitrokey.trussed.admin\_app
+===========================
+
+.. automodule:: nitrokey.trussed.admin_app
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/nitrokey.trussed.provisioner_app.rst

@@ -0,0 +1,7 @@
+nitrokey.trussed.provisioner\_app
+=================================
+
+.. automodule:: nitrokey.trussed.provisioner_app
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/nitrokey.trussed.rst

@@ -0,0 +1,85 @@
+nitrokey.trussed
+================
+
+.. automodule:: nitrokey.trussed
+
+.. rubric:: Submodules
+
+.. toctree::
+   :maxdepth: 1
+
+   nitrokey.trussed.admin_app
+   nitrokey.trussed.provisioner_app
+
+Trussed Device Objects
+----------------------
+
+.. autoclass:: nitrokey.trussed.TrussedBase
+   :members:
+   :undoc-members:
+
+.. autoclass:: nitrokey.trussed.TrussedDevice
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: nitrokey.trussed.TrussedBootloader
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Update Container Objects
+------------------------
+
+.. autofunction:: nitrokey.trussed.parse_firmware_image
+
+.. autoclass:: nitrokey.trussed.FirmwareContainer
+   :members:
+   :undoc-members:
+
+.. autoclass:: nitrokey.trussed.FirmwareMetadata
+   :members:
+   :undoc-members:
+
+.. autoclass:: nitrokey.trussed.Variant
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Utility Objects
+---------------
+
+.. autoclass:: nitrokey.trussed.App
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: nitrokey.trussed.Fido2Certs
+   :members:
+   :undoc-members:
+
+.. autoclass:: nitrokey.trussed.Model
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: nitrokey.trussed.Uuid
+   :members:
+   :undoc-members:
+
+.. autoclass:: nitrokey.trussed.Version
+   :members:
+   :undoc-members:
+
+Trussed Exceptions
+------------------
+
+.. autoclass:: nitrokey.trussed.TrussedException
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: nitrokey.trussed.TimeoutException
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/nitrokey.updates.rst

@@ -0,0 +1,7 @@
+nitrokey.updates
+================
+
+.. automodule:: nitrokey.updates
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/conf.py

@@ -0,0 +1,11 @@
+project = 'Nitrokey Python SDK'
+copyright = '2024, Nitrokey'
+author = 'Nitrokey'
+release = '0.1.0'
+extensions = [
+    'sphinx.ext.autodoc',
+]
+html_theme = 'alabaster'
+autodoc_class_signature = 'separated'
+autodoc_member_order = 'groupwise'
+autodoc_typehints = 'description'

docs/guides/index.rst

@@ -0,0 +1,7 @@
+Guides
+======
+
+.. toctree::
+   :maxdepth: 1
+
+   usage

docs/guides/usage.rst

@@ -0,0 +1,58 @@
+Usage Guide
+===========
+
+.. contents:: :local:
+
+The Nitrokey Python SDK currently supports Nitrokey 3 (:py:class:`nitrokey.nk3.NK3`) and Nitrokey Passkey (:py:class:`nitrokey.nkpk.NKPK`) devices.
+Both devices are based on the same platform, Trussed, and therefore share the same base class :py:class:`nitrokey.trussed.TrussedDevice`.
+
+Trussed devices can be rebooted into a bootloader mode that is used to apply firmware updates.
+Devices in bootloader mode can be accessed using :py:class:`nitrokey.nk3.NK3Bootloader` and :py:class:`nitrokey.nkpk.NKPKBootloader` (base class :py:class:`nitrokey.trussed.TrussedBootloader`).
+
+Listing and Opening Devices
+---------------------------
+
+Use the :py:meth:`nitrokey.trussed.TrussedDevice.list` function to list and open all connected devices::
+
+    from nitrokey.nk3 import NK3
+    from nitrokey.nkpk import NKPK
+
+    print("Connected Nitrokey devices:")
+    for device in NK3.list():
+        print(f"- {device.name} at {device.path}")
+    for device in NKPK.list():
+        print(f"- {device.name} at {device.path}")
+
+If you know the device path, use :py:meth:`nitrokey.trussed.TrussedDevice.open` instead::
+
+    from nitrokey.nk3 import NK3
+    from nitrokey.nkpk import NKPK
+
+    path = "/dev/hidraw1"
+    device = NK3.open(path)
+    if device is not None:
+        print(f"Found {device.name} at {path}")
+    device = NKPK.open(path)
+    if device is not None:
+        print(f"Found {device.name} at {path}")
+
+Similar functions are available for :py:class:`nitrokey.nk3.NK3Bootloader` and :py:class:`nitrokey.nkpk.NKPKBootloader`.
+To list both normal and bootloader devices, use :py:meth:`nitrokey.nk3.list` and :py:meth:`nitrokey.nkpk.list`.
+
+.. note::
+   Currently, the devices returned by :py:meth:`nitrokey.trussed.TrussedDevice.list`, :py:meth:`nitrokey.nk3.list` and :py:meth:`nitrokey.nkpk.list` are only valid until the next call to any of the these functions.
+   See `issue 31 <https://github.com/Nitrokey/nitrokey-sdk-py/issues/31>`_ for more information.
+
+Using Applications
+------------------
+
+The Nitrokey Python SDK supports these applications for all Trussed devices:
+
+* :py:class:`nitrokey.trussed.admin_app.AdminApp`: access device metadata and manage device configuration state
+* :py:class:`nitrokey.trussed.provisioner_app.ProvisionerApp`: setup device in provisioner mode (only applicable for Hacker devices)
+
+The Nitrokey 3 also provides these applications:
+
+* :py:class:`nitrokey.nk3.secrets_app.SecretsApp`: securely store passwords and credentials
+
+See the API reference for the application classes for more information.

docs/index.rst

@@ -0,0 +1,9 @@
+Nitrokey Python SDK
+===================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   guides/index
+   api/index