add module level docstrings (#8)

* add module level docstrings

* fmt

* add docstring to init

* Update pyrot/eye_modelling/__init__.py

Co-authored-by: crnh <30109443+crnh@users.noreply.github.com>

* Update pyrot/eye_modelling/datamodels/__init__.py

Co-authored-by: crnh <30109443+crnh@users.noreply.github.com>

* Format docstrings

* (re)write docstrings

* Do not generate documentation for undocumented members

* Fix datamodels docstring

---------

Co-authored-by: crnh <30109443+crnh@users.noreply.github.com>

Author: jwmbeenakker

.github/workflows/ci.yml

@@ -27,4 +27,7 @@ jobs:
       - name: Install Python
         run: uv python install ${{ matrix.python-version }}
       - name: Run tests
-        run: uvx hatch test
+        run: uvx hatch test
+      - name: Lint docstrings
+        if: always() # Run even if previous step fails
+        run: uvx pydocstringformatter --exit-code scripts tests pyrot standalone

docs/conf.py

@@ -91,8 +91,8 @@
 
 autoapi_dirs = ["../pyrot"]
 autoapi_root = "api"
-# autoapi_options = [
-#     "members",
-#     "show-inheritance",
-#     "show-module-summary",
-# ]
+autoapi_options = [
+    "members",
+    "show-inheritance",
+    "show-module-summary",
+]

pyproject.toml

@@ -35,6 +35,14 @@ exclude = [".github/", "docs/"]
 [tool.hatch.build.targets.wheel]
 packages = ["pyrot"]
 
+[tool.hatch.envs.default]
+installer = "uv"
+python = "3.8"
+
+[tool.hatch.envs.default.scripts]
+# Format docstrings according to numpydoc
+format-docstrings = "{env:HATCH_UV:uv} tool run pydocstringformatter --write {args:scripts tests pyrot standalone}"
+
 # Testing
 
 [[tool.hatch.envs.hatch-test.matrix]]
@@ -109,3 +117,10 @@ convention = "numpy"
 
 [tool.ruff.format]
 quote-style = "double"
+
+[tool.pydocstringformatter]
+style = "numpydoc"
+max-line-length = 120
+max-summary-lines = 1
+summary-quotes-same-line = true
+linewrap-full-docstring = true

pyrot/__init__.py

@@ -1,3 +1,10 @@
+"""PyROT: Python RayOcular Tools.
+
+A set of tools to work with eye models in Python. This library is designed to be as vendor-agnostic
+as possible, allowing it to be used without RayStation. Interactions with RayStation are handled
+through the `ro_interface` module.
+"""
+
 from __future__ import annotations
 
 from pyrot import ro_interface

pyrot/config.py

@@ -1,3 +1,5 @@
+"""Configuration for pyROT."""
+
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Literal
@@ -9,8 +11,9 @@
 
 
 class Config:
-    r"""Configuration for pyROT.
-    Settings can be overwritten by `scripts\customization.py`, which is imported by `__common__.py`.
+    """Configuration for pyROT.
+
+    Settings can be overwritten by scripts/customization.py, which is imported by `__common__.py`.
     """
 
     ELLIPSOID_FIT_MINIMUM_MATRIX_CONDITION: float = 100
@@ -39,9 +42,9 @@ class Config:
     """The eye model number. Needs to be altered/ checked in the case of multiple eye models."""
 
     ROI_EXPORT_UNIT: Literal["Centimeter", "Millimeter"] = "Centimeter"
-    """The unit in which rois are exported."""
+    """The unit in which ROIs are exported."""
 
-    ROI_EXPORT_ROI_SUFFIX: str = None
+    ROI_EXPORT_ROI_SUFFIX: str | None = None
     """The suffix after the roi name of the rois that need to be exported.
 
     By default, there is no suffix in RayOcular.

pyrot/eye_modelling/__init__.py

@@ -1,3 +1,26 @@
+"""Eye modelling
+=============
+
+The eye_modelling module provides methods matching the geometric eye-model to imaging and biometry data.
+
+Notes
+-----
+The methods used in this package are based on the work of Pors et al. (submitted)
+
+Modules
+-------
+clipbased_model
+    Match a clip-based eye model to the clips.
+common_methods
+    Shared utility functions and methods for eye modeling.
+ellipsoid_fit
+    Functions for fitting an ellipsoid to POIs.
+match_sclera_to_markers
+    Methods for matching sclera ellipse to POIs.
+match_with_biometry
+    Methods to determine the best-fitting eye-model based on imaging and biometry data.
+"""
+
 from __future__ import annotations
 
 from pyrot.eye_modelling import (

pyrot/eye_modelling/clipbased_model.py

@@ -1,3 +1,5 @@
+"""Create eye models based on clip locations and optic disk location."""
+
 from __future__ import annotations
 
 import logging
@@ -15,9 +17,10 @@
 def match_ellipse_with_pois(
     eye_model_generators, eye_model_parameters, structure_set, input_ellipse, poi_type_clips, poi_type_on
 ):
-    """
-    Aligns the eye model's translation and rotation to best fit known clip locations (POIs) and the optic disk location.
-    This function updates the eye model center and rotation so that the model's sclera surface matches the positions of physical markers (clips) and the optic disk.
+    """Aligns the eye model's translation and rotation to best fit known clip locations (POIs) and the optic disk
+    location.
+    This function updates the eye model center and rotation so that the model's sclera surface matches the positions of
+    physical markers (clips) and the optic disk.
 
     Parameters
     ----------
@@ -99,8 +102,7 @@ def match_ellipse_with_pois(
 
 
 def calc_on_model_loc_patient(geometry_generators, eye_model_parameters, on_model_loc_method):
-    """
-    Calculates the location of the optic nerve ROI on the unity circle for a given eye model.
+    """Calculates the location of the optic nerve ROI on the unity circle for a given eye model.
 
     This function determines the standardized location of the optic disk as if the eye model were positioned at the origin
     ([0, 0, 0]) with input angles [0, 0, 0] and sclera radii [1, 1, 1]. This is necessary for fitting procedures that
@@ -179,8 +181,7 @@ def calc_on_model_loc_patient(geometry_generators, eye_model_parameters, on_mode
 
 
 def registration_residuals(params, clip_data, optic_nerve_data, axes):
-    """
-    Compute the residuals for ellipsoid registration and optic nerve location alignment.
+    """Compute the residuals for ellipsoid registration and optic nerve location alignment.
 
     This function calculates the residuals between a set of 3D points (clip_data) and an ellipsoid model,
     as well as the normalized distance between the transformed optic nerve location and its model POI.
@@ -260,8 +261,7 @@ def registration_residuals(params, clip_data, optic_nerve_data, axes):
 
 
 def calc_ellipsoid_registration(clip_data, on_model_loc, on_image_loc, axes, initial_guess=None):
-    """
-    Perform ellipsoid registration to align clip data and optic nerve locations.
+    """Perform ellipsoid registration to align clip data and optic nerve locations.
 
     This function calculates the optimal translation and rotation parameters to align
     a set of 3D points (clip_data) with an ellipsoid defined by the given axes, while

pyrot/eye_modelling/common_methods.py

@@ -1,3 +1,5 @@
+"""Common methods for eye modelling."""
+
 from __future__ import annotations
 
 import logging
@@ -9,8 +11,7 @@
 
 
 def getTranslationMatrix(x: float, y: float, z: float) -> np.ndarray:
-    """
-    Generate a translation matrix for 3D transformations.
+    """Generate a translation matrix for 3D transformations.
 
     Parameters
     ----------
@@ -30,8 +31,7 @@ def getTranslationMatrix(x: float, y: float, z: float) -> np.ndarray:
 
 
 def toRadians(angleDegrees: float) -> float:
-    """
-    Convert an angle from degrees to radians.
+    """Convert an angle from degrees to radians.
 
     Parameters
     ----------
@@ -47,8 +47,7 @@ def toRadians(angleDegrees: float) -> float:
 
 
 def toDegrees(angleRadians: float) -> float:
-    """
-    Convert an angle from radians to degrees.
+    """Convert an angle from radians to degrees.
 
     Parameters
     ----------
@@ -64,8 +63,7 @@ def toDegrees(angleRadians: float) -> float:
 
 
 def getIdentityMatrix() -> np.ndarray:
-    """
-    Returns a 4x4 identity matrix.
+    """Returns a 4x4 identity matrix.
 
     Returns
     -------
@@ -76,8 +74,7 @@ def getIdentityMatrix() -> np.ndarray:
 
 
 def getRotationMatrixX(angleDeg: float) -> np.ndarray:
-    """
-    Calculate the rotation matrix for a rotation around the X-axis.
+    """Calculate the rotation matrix for a rotation around the X-axis.
 
     Parameters
     ----------
@@ -96,8 +93,7 @@ def getRotationMatrixX(angleDeg: float) -> np.ndarray:
 
 
 def getRotationMatrixY(angleDeg: float) -> np.ndarray:
-    """
-    Generate a rotation matrix for a rotation around the Y-axis.
+    """Generate a rotation matrix for a rotation around the Y-axis.
 
     Parameters
     ----------
@@ -116,8 +112,7 @@ def getRotationMatrixY(angleDeg: float) -> np.ndarray:
 
 
 def getRotationMatrixZ(angleDeg: float) -> np.ndarray:
-    """
-    Generate a rotation matrix for a rotation around the Z-axis.
+    """Generate a rotation matrix for a rotation around the Z-axis.
 
     Parameters
     ----------
@@ -136,8 +131,7 @@ def getRotationMatrixZ(angleDeg: float) -> np.ndarray:
 
 
 def getEyeModelGeometry(eyeModel: object, structureType: str) -> object:
-    """
-    Retrieve the geometry for a specific structure type from the eye model.
+    """Retrieve the geometry for a specific structure type from the eye model.
 
     Parameters
     ----------
@@ -161,8 +155,7 @@ def getEyeModelGeometry(eyeModel: object, structureType: str) -> object:
 
 
 def getClipGeometries(eyeModel: object) -> list:
-    """
-    Retrieve all clip geometries from the eye model.
+    """Retrieve all clip geometries from the eye model.
 
     Parameters
     ----------
@@ -178,8 +171,7 @@ def getClipGeometries(eyeModel: object) -> list:
 
 
 def getEyeModelToPatientRotationMatrix(rotationXDeg: float, rotationYDeg: float, rotationZDeg: float) -> np.ndarray:
-    """
-    Calculate the rotation matrix to transform from eye model coordinates to patient coordinates.
+    """Calculate the rotation matrix to transform from eye model coordinates to patient coordinates.
 
     Parameters
     ----------

pyrot/eye_modelling/datamodels/__init__.py

@@ -1,3 +1,8 @@
+"""Data structures for eye models in RayOcular.
+
+This package provides classes and functions to interact with eye models in RayOcular.
+"""
+
 from __future__ import annotations
 
 from pyrot.eye_modelling.datamodels import export, models, validators

pyrot/eye_modelling/datamodels/export.py

@@ -1,3 +1,5 @@
+"""Export eye model geometries and regions of interest from RayOcular."""
+
 from __future__ import annotations
 
 import json
@@ -24,8 +26,7 @@ def full_export(
     export_suffix: str,
     roi_export_unit: Literal["Millimeters", "Centimeters"],
 ):
-    """
-    Exports all relevant data for a given eye model to a structured output directory.
+    """Exports all relevant data for a given eye model to a structured output directory.
     This function gathers patient, case, and examination information, creates a uniquely named
     export directory, and exports ROI geometries, eye model data, and points of interest (POIs)
     for the specified eye model number.
@@ -95,10 +96,11 @@ def export_roi_geometries(
     export_suffix: str,
     roi_export_unit: str,
 ):
-    """
-    Exports ROI geometries from a given structure set to STL files.
-    The function iterates over the ROI geometries in the provided structure set, filters them based on the specified export suffix,
-    and exports each selected geometry as an STL file to the specified output directory. Exported files are named according to the ROI name,
+    """Exports ROI geometries from a given structure set to STL files.
+    The function iterates over the ROI geometries in the provided structure set, filters them based on the specified
+    export suffix,
+    and exports each selected geometry as an STL file to the specified output directory. Exported files are named
+    according to the ROI name,
     with spaces replaced by underscores, and include the export unit in the filename.
 
     Parameters
@@ -168,8 +170,7 @@ def export_roi_geometries(
 
 
 def export_eye_model(structure_set, output_directory: Path, eyemodelnr: int):
-    """
-    Export an eye model to a JSON file.
+    """Export an eye model to a JSON file.
 
     Parameters
     ----------
@@ -198,8 +199,7 @@ def export_eye_model(structure_set, output_directory: Path, eyemodelnr: int):
 
 
 def export_pois(structure_set, output_directory: Path, examination_name: str):
-    """
-    Exports points of interest (POIs) from a structure set to a JSON file.
+    """Exports points of interest (POIs) from a structure set to a JSON file.
 
     Parameters
     ----------