Documentation

README.md

@@ -6,6 +6,8 @@
 
 **Source Code**: <a href="https://github.com/bag-cnag/biodm" target="_blank">https://github.com/bag-cnag/biodm</a>
 
+**Documentation**: Not hosted yet, please refer to [build documentation](#build-documentation).
+
 ---
 
 BioDM is a fast, stateless and asynchronous REST API framework with the following core features:
@@ -46,8 +48,9 @@ Then you may run our `example` after populating  `src/example/config.py` with yo
 python3 src/example/app.py
 ```
 
-### Generate documentation
+### Build documentation
 ```bash
+pip3 install -r src/requirements/docs.txt
 sphinx-apidoc --implicit-namespaces -fo docs/biodm/ src/biodm -H "API Reference"
 python3 -m sphinx -b html docs/ docs/build/html
 ```
@@ -121,7 +124,7 @@ then
 docker run --name local_keycloak -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin -p 8443:8080 keycloak:22.0.5_local-certs
 ```
 
-**Configuration:**
+- **Configuration**:
 
 Once keycloak is running you need to configure a realm and a client for the app to log in.
 Default values are:

src/biodm/api.py

@@ -23,7 +23,7 @@
 from biodm.tables import History, ListGroup
 from biodm import __version__ as CORE_VERSION
 try:
-    import kubernetes as k8s
+    import kubernetes
     HAS_K8s = True
 except:
     HAS_K8s = False

src/biodm/error.py

@@ -2,7 +2,7 @@
 from http import HTTPStatus
 
 from starlette.responses import Response
-# from sqlalchemy.exc import DatabaseError
+
 from .exceptions import (
     RequestError,
     FailedDelete,
@@ -13,6 +13,7 @@
 
 
 class Error:
+    """Error class."""
     def __init__(self, status, detail=None):
         self.status = status
         self.detail = detail
@@ -32,8 +33,10 @@ def response(self):
         )
 
 
-# https://restfulapi.net/http-status-codes/
 async def onerror(_, exc):
+    """Error event handler.
+
+    Relevant documentation: https://restfulapi.net/http-status-codes/"""
     status = 500
     detail = None
 

src/biodm/exceptions.py

@@ -43,11 +43,10 @@ class PayloadValidationError(RuntimeError):
 
 
 ## Routing
-class InvalidCollectionMethod(RuntimeError):
+class InvalidCollectionMethod(RequestError):
     """Raised when a unit method is accesed as a collection."""
-    def __init__(self, _, orig=None):
-        detail = "Method not allowed on a collection."
-        super().__init__(detail=detail)
+    def __init__(self, *_):
+        super().__init__(detail="Method not allowed on a collection.")
 
 
 class UnauthorizedError(RequestError):

src/requirements/dev.txt

@@ -1,4 +1,3 @@
 -r common.txt
 kubernetes==29.0.0
 pytest==8.1.1
-Sphinx==7.3.7

src/requirements/docs.txt

@@ -0,0 +1,4 @@
+-r dev.txt
+Sphinx==7.3.7
+sphinx-rtd-theme==2.0.0
+sphinx-pyproject==0.3.0