Add module level docstrings.

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

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

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",

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

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/

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

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

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
 

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
 

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

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

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

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

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

tests/test_scan_directories.py

@@ -1,3 +1,5 @@
+"""Test the functionality in the scan_directories module."""
+
 import tempfile
 import os
 import math

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
 

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