From 2cb40038357dac95182c364851c6f56f0c9da635 Mon Sep 17 00:00:00 2001
From: Julian Stirling <julian@julianstirling.co.uk>
Date: Thu, 10 Jul 2025 08:59:27 +0100
Subject: [PATCH] Add module level docstrings.

---
 .../picamera2/test_acquisition.py                   |  2 ++
 .../picamera2/test_sensor_mode.py                   |  2 ++
 pyproject.toml                                      |  1 -
 scripts/zenodo/upload_to_zenodo.py                  |  2 ++
 scripts/zenodo/zenodo.py                            |  2 +-
 src/openflexure_microscope_server/logging.py        | 13 +++++++++++++
 .../server/legacy_api.py                            |  2 ++
 .../server/serve_static_files.py                    |  2 ++
 .../things/auto_recentre_stage.py                   |  2 ++
 .../things/background_detect.py                     |  7 +++++++
 .../things/smart_scan.py                            |  9 +++++++++
 .../things/stage/dummy.py                           |  2 ++
 .../things/stage/sangaboard.py                      |  2 ++
 tests/test_dummy_server.py                          | 10 ++++++++++
 tests/test_scan_directories.py                      |  2 ++
 tests/test_scan_planners.py                         |  6 ++++++
 tests/utilities/scan_test_helpers.py                |  6 ++++++
 17 files changed, 70 insertions(+), 2 deletions(-)

diff --git a/hardware-specific-tests/picamera2/test_acquisition.py b/hardware-specific-tests/picamera2/test_acquisition.py
index 483c200f..b8e2fe88 100644
--- a/hardware-specific-tests/picamera2/test_acquisition.py
+++ b/hardware-specific-tests/picamera2/test_acquisition.py
@@ -1,3 +1,5 @@
+"""Test data collection from the Raspberry Picamera."""
+
 from fastapi.testclient import TestClient
 from PIL import Image
 import numpy as np
diff --git a/hardware-specific-tests/picamera2/test_sensor_mode.py b/hardware-specific-tests/picamera2/test_sensor_mode.py
index 9b738065..af875d9c 100644
--- a/hardware-specific-tests/picamera2/test_sensor_mode.py
+++ b/hardware-specific-tests/picamera2/test_sensor_mode.py
@@ -1,3 +1,5 @@
+"""Test changing and setting camerat modes on the Raspberry Picamera."""
+
 import logging
 
 from fastapi.testclient import TestClient
diff --git a/pyproject.toml b/pyproject.toml
index 531b8d30..3e55e518 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -129,7 +129,6 @@ ignore = [
     "D213",  # incompatible with D212
     "D400",  # A stricter version of #415 that doesn't allow !
     # The checkers below should be turned on as they complain about missing docstrings.
-    "D100",
     "D102",
     "D101",
     "D103",
diff --git a/scripts/zenodo/upload_to_zenodo.py b/scripts/zenodo/upload_to_zenodo.py
index 3fff944f..d52eeeb4 100644
--- a/scripts/zenodo/upload_to_zenodo.py
+++ b/scripts/zenodo/upload_to_zenodo.py
@@ -1,3 +1,5 @@
+"""A script for uploading data to Zenodo."""
+
 import os
 from argparse import ArgumentParser, Namespace
 from zenodo import Zenodo
diff --git a/scripts/zenodo/zenodo.py b/scripts/zenodo/zenodo.py
index c343ed6d..6a0a0380 100644
--- a/scripts/zenodo/zenodo.py
+++ b/scripts/zenodo/zenodo.py
@@ -1,4 +1,4 @@
-"""A script for uploading to zenodo.
+"""A script for packaging data for Zenodo.
 
 Copyright (c) 2020 Bath Open Instrumentation Group
 Adapted from: https://gitlab.com/schlauch/zenodo-api-test/
diff --git a/src/openflexure_microscope_server/logging.py b/src/openflexure_microscope_server/logging.py
index dfad0937..a7cf580d 100644
--- a/src/openflexure_microscope_server/logging.py
+++ b/src/openflexure_microscope_server/logging.py
@@ -1,3 +1,16 @@
+"""Configure logging for the OpenFlexure Server.
+
+A module containing a custom logging handler and helper function for
+the OpenFlexure server. These handle formatting logs, ensuring that logs
+are logged both to a file and to the terminal (see note below!). Functionality
+is also provided for retrieving logs for to send over HTTP.
+
+Note that when running in production OpenFlexure Microscope the server is run via
+``systemd``. As such, the logs that are sent to the terminal (STDERR) or any other
+output to STDOUT/STDERR are captured by ``systemd``. These can be viewed by using
+``journalctl`` or the ``ofm journal`` command.
+"""
+
 import logging
 from logging.handlers import RotatingFileHandler
 import os
diff --git a/src/openflexure_microscope_server/server/legacy_api.py b/src/openflexure_microscope_server/server/legacy_api.py
index 1742cfe2..6cca9c30 100644
--- a/src/openflexure_microscope_server/server/legacy_api.py
+++ b/src/openflexure_microscope_server/server/legacy_api.py
@@ -1,3 +1,5 @@
+"""Provide endpoints that mimic the v2 API for OpenFlexure Connect discoverability."""
+
 import labthings_fastapi as lt
 from fastapi import Response
 from socket import gethostname
diff --git a/src/openflexure_microscope_server/server/serve_static_files.py b/src/openflexure_microscope_server/server/serve_static_files.py
index af708f2e..fc54d50c 100644
--- a/src/openflexure_microscope_server/server/serve_static_files.py
+++ b/src/openflexure_microscope_server/server/serve_static_files.py
@@ -1,3 +1,5 @@
+"""Add endpoints for static files to the underlying FastAPI server."""
+
 import os
 from typing import Optional
 
diff --git a/src/openflexure_microscope_server/things/auto_recentre_stage.py b/src/openflexure_microscope_server/things/auto_recentre_stage.py
index 2b68bbbc..956e415e 100644
--- a/src/openflexure_microscope_server/things/auto_recentre_stage.py
+++ b/src/openflexure_microscope_server/things/auto_recentre_stage.py
@@ -1,3 +1,5 @@
+"""Provide functionality for automatically recentring the Stage."""
+
 import numpy as np
 import logging
 
diff --git a/src/openflexure_microscope_server/things/background_detect.py b/src/openflexure_microscope_server/things/background_detect.py
index 7ada837f..bdc44e84 100644
--- a/src/openflexure_microscope_server/things/background_detect.py
+++ b/src/openflexure_microscope_server/things/background_detect.py
@@ -1,3 +1,10 @@
+"""Provide functionality to detect if the camera is imaging sample or background.
+
+An example background image must be captured and analysed by BackgroundDetectThing,
+information from this images is used to detect whether the current camera field of
+view contains sample.
+"""
+
 from typing import Mapping, Optional
 import cv2
 import numpy as np
diff --git a/src/openflexure_microscope_server/things/smart_scan.py b/src/openflexure_microscope_server/things/smart_scan.py
index d2d7b695..d85e6a83 100644
--- a/src/openflexure_microscope_server/things/smart_scan.py
+++ b/src/openflexure_microscope_server/things/smart_scan.py
@@ -1,3 +1,12 @@
+"""The core sample scanning functionality for the OpenFlexure Microscope.
+
+SmartScan provides sample scanning functionality including automatic background
+dectection (via the `BackgroundDetectThing`) and automatic path planning via
+`scan_planners`. It manages the directories of past scans via `scan_directories`.
+It also controls external processes for live stitching composite images, and
+the creation of the final stitched images.
+"""
+
 from typing import Optional, Mapping
 import threading
 import os
diff --git a/src/openflexure_microscope_server/things/stage/dummy.py b/src/openflexure_microscope_server/things/stage/dummy.py
index 499eb761..44d031a4 100644
--- a/src/openflexure_microscope_server/things/stage/dummy.py
+++ b/src/openflexure_microscope_server/things/stage/dummy.py
@@ -1,3 +1,5 @@
+"""Functionality for mimicking a stage during simulation and testing."""
+
 from __future__ import annotations
 
 from collections.abc import Mapping
diff --git a/src/openflexure_microscope_server/things/stage/sangaboard.py b/src/openflexure_microscope_server/things/stage/sangaboard.py
index 641990f9..cd3e4f3a 100644
--- a/src/openflexure_microscope_server/things/stage/sangaboard.py
+++ b/src/openflexure_microscope_server/things/stage/sangaboard.py
@@ -1,3 +1,5 @@
+"""Provide a LabThings-FastAPI interface to the Sangaboard motor controller."""
+
 from __future__ import annotations
 import logging
 import threading
diff --git a/tests/test_dummy_server.py b/tests/test_dummy_server.py
index ca286ebd..fd62ca5e 100644
--- a/tests/test_dummy_server.py
+++ b/tests/test_dummy_server.py
@@ -1,3 +1,13 @@
+"""Test the server without creating a full HTTP server and socket connection.
+
+Rather than spinning up a full uvicorn webserver for each test these tests use
+the FastAPI ``TestClient`` or to directly communicate with the underlying
+LabThings-FastAPI code. This increases speed of testing significantly.
+
+For tests that require a full running server see the ``integration-tests``
+directory in the root of the repository.
+"""
+
 import json
 import os
 import tempfile
diff --git a/tests/test_scan_directories.py b/tests/test_scan_directories.py
index b66180bf..1f6c0609 100644
--- a/tests/test_scan_directories.py
+++ b/tests/test_scan_directories.py
@@ -1,3 +1,5 @@
+"""Test the functionality in the scan_directories module."""
+
 import tempfile
 import os
 import math
diff --git a/tests/test_scan_planners.py b/tests/test_scan_planners.py
index 4980cae4..10f02a58 100644
--- a/tests/test_scan_planners.py
+++ b/tests/test_scan_planners.py
@@ -1,3 +1,9 @@
+"""Test the scan planning algorithms of the Microscope.
+
+As well as low level function by function tests, this test suite also provides tests
+that simulate scanning a sample, checking that the expected path is followed.
+"""
+
 import pytest
 from copy import copy
 
diff --git a/tests/utilities/scan_test_helpers.py b/tests/utilities/scan_test_helpers.py
index 7052c579..2faf4253 100644
--- a/tests/utilities/scan_test_helpers.py
+++ b/tests/utilities/scan_test_helpers.py
@@ -1,3 +1,9 @@
+"""Utility functions for testing scan planners.
+
+These including fake sample creation, scan path visualisation, and
+persistent storage of expected scan paths for samples.
+"""
+
 import os
 import pickle