docs: add docstrings and fix ruff warnings

Author: MattTheCuber

.gitignore

@@ -3,6 +3,7 @@ __pycache__/
 *.egg-info/
 dist/
 build/
+.coverage
 
 *.stl
 *.obj

edge_mender/edge_mender.py

@@ -44,6 +44,12 @@ def __init__(self, mesh: trimesh.Trimesh, *, debug: bool = False) -> None:
     def validate(self, *, spacing: tuple[float, float, float]) -> None:
         """Validate that the mesh is a valid voxel boundary mesh before repair.
 
+        Parameters
+        ----------
+        spacing : tuple[float, float, float]
+            The spacing of the mesh in each dimension. This is used to check that the
+            face areas are uniform and that the angles are correct.
+
         Raises
         ------
         ValueError
@@ -83,16 +89,42 @@ def validate(self, *, spacing: tuple[float, float, float]) -> None:
             msg = f"WARNING: Mesh has {unique_areas} unique non-uniform face areas."
             raise ValueError(msg)
 
-    def find_non_manifold_edges(self) -> tuple[NDArray, NDArray, NDArray]:
+    def find_non_manifold_edges(
+        self,
+    ) -> tuple[NDArray[np.int64], NDArray[np.int64], NDArray[np.int64]]:
+        """Find non-manifold edges within the mesh.
+
+        Non-manifold edges are defined as edges shared by 4 faces.
+
+        Returns
+        -------
+        non_manifold_faces : NDArray[np.int64]
+            An (n, 4) array of the four face indices for each non-manifold edge.
+        non_manifold_vertices : NDArray[np.int64]
+            An (n, 2) array of the two vertex indices for each non-manifold edge.
+        non_manifold_edges : NDArray[np.int64]
+            An (n,) array of the edge indices for each non-manifold edge.
+
+        Raises
+        ------
+        ValueError
+            If there is a problem with the edge face lookup.
+        """
+        # Find all unique edges and their face counts
         unique_edges, counts = np.unique(
             self.mesh.faces_unique_edges.flatten(),
             return_counts=True,
         )
+        # Find the edges that are shared by 4 faces
         edges = unique_edges[counts == NON_MANIFOLD_EDGE_FACE_COUNT]
+
+        # Get the vertices for each edge
         vertices = self.mesh.edges_unique[edges]
 
+        # Get the faces for each edge
         distance_check, edge_index = self.mesh.edges_sorted_tree.query(
-            vertices, k=NON_MANIFOLD_EDGE_FACE_COUNT
+            vertices,
+            k=NON_MANIFOLD_EDGE_FACE_COUNT,
         )
         if np.any(distance_check):
             msg = "Problem with edge face lookup"

edge_mender/tests/test_edge_mender.py

@@ -1,12 +1,15 @@
+"""Test major functions in the EdgeMender class."""
+
 import pytest
 import trimesh
+from numpy.typing import NDArray
 
 from edge_mender.data_factory import DataFactory
 from edge_mender.edge_mender import EdgeMender
 from edge_mender.mesh_generator import MeshGenerator
 
 
-@pytest.mark.parametrize("spacing", [[1, 1, 1], [1.25, 0.5, 0.25]])
+@pytest.mark.parametrize("spacing", [(1, 1, 1), (1.25, 0.5, 0.25)])
 @pytest.mark.parametrize(
     "data",
     [
@@ -20,22 +23,25 @@
         DataFactory.checkerboard(),
     ],
 )
-def test_validate(data, spacing):
+def test_validate(data: NDArray, spacing: tuple[float, float, float]) -> None:
+    """Test that the validate function works for valid meshes."""
     mesh = MeshGenerator.to_mesh_surface_nets(data)
     mesh.vertices *= spacing
     mender = EdgeMender(mesh)
     mender.validate(spacing=spacing)
 
 
-def test_validate_fail_normals():
+def test_validate_fail_normals() -> None:
+    """Test that the validate function fails for non-axis-aligned face normals."""
     # Pyramid with non-axis-aligned face normals
     mesh = trimesh.creation.cone(1, 1, sections=3)
     mender = EdgeMender(mesh)
     with pytest.raises(ValueError, match="non-axis-aligned face normals"):
         mender.validate(spacing=(1, 1, 1))
 
 
-def test_validate_fail_angles():
+def test_validate_fail_angles() -> None:
+    """Test that the validate function fails for non-standard degree angles."""
     mesh = trimesh.creation.box()
     # Stretch the box to create bad angles
     mesh.vertices *= [1, 1, 1.25]
@@ -44,7 +50,8 @@ def test_validate_fail_angles():
         mender.validate(spacing=(1, 1, 1))
 
 
-def test_validate_fail_areas():
+def test_validate_fail_areas() -> None:
+    """Test that the validate function fails for non-uniform face areas."""
     # Subdivide everything except one face to make the faces larger
     mesh = trimesh.creation.box().subdivide(list(range(10)))
     mender = EdgeMender(mesh)

edge_mender/tests/test_geometry_helper.py

@@ -1,3 +1,5 @@
+"""Test the GeometryHelper class."""
+
 import numpy as np
 import pytest
 
@@ -13,10 +15,17 @@
         ([0, 0], [0, 1], [-1, 0], True),
         ([0, 0], [1, 0], [1, 1], True),
         ([0, 0], [1, 0], [1, -1], False),
-        ([0, 0], [1, 0], [2, 0], ValueError),
+        ([0, 0], [1, 0], [2, 0], "Point is on the line"),
     ],
 )
-def test_is_left(line_point, line_direction, test_point, expected):
+def test_is_left(
+    line_point: list[int],
+    line_direction: list[int],
+    test_point: list[int],
+    *,
+    expected: bool | str,
+) -> None:
+    """Test GeometryHelper.is_left."""
     if isinstance(expected, bool):
         assert (
             GeometryHelper.is_left(
@@ -27,7 +36,7 @@ def test_is_left(line_point, line_direction, test_point, expected):
             == expected
         )
     else:
-        with pytest.raises(expected):
+        with pytest.raises(ValueError, match=expected):
             GeometryHelper.is_left(
                 line_point=np.array(line_point),
                 line_direction=np.array(line_direction),
@@ -50,7 +59,13 @@ def test_is_left(line_point, line_direction, test_point, expected):
         ([0, 1, 1], [1, 1, 1], [1, 0, 0], 180),
     ],
 )
-def test_angle_between_point_and_ray(point, ray_point, ray_dir, expected_angle):
+def test_angle_between_point_and_ray(
+    point: list[int],
+    ray_point: list[int],
+    ray_dir: list[int],
+    expected_angle: int,
+) -> None:
+    """Test GeometryHelper.angle_between_point_and_ray."""
     angle = GeometryHelper.angle_between_point_and_ray(
         point=np.array(point),
         ray_point=np.array(ray_point),
@@ -69,7 +84,15 @@ def test_angle_between_point_and_ray(point, ray_point, ray_dir, expected_angle):
         ([0, 0], [1, 0], [1, 0], [-1, 0], "Colinear"),
     ],
 )
-def test_rays_intersect(point_1, normal_1, point_2, normal_2, expected):
+def test_rays_intersect(
+    point_1: list[int],
+    normal_1: list[int],
+    point_2: list[int],
+    normal_2: list[int],
+    *,
+    expected: bool | str,
+) -> None:
+    """Test GeometryHelper.rays_intersect."""
     if isinstance(expected, bool):
         assert (
             GeometryHelper.rays_intersect(

pyproject.toml

@@ -25,6 +25,7 @@ test = [
 ]
 dev = [
     "pytest>=8.4.2",
+    "pytest-cov>=7.0.0",
     "ruff>=0.14.1",
     "uv>=0.9.5",
     "cython>=3.1.5",
@@ -55,3 +56,6 @@ unfixable = []
 
 [tool.ruff.lint.pydocstyle]
 convention = "numpy"
+
+[tool.ruff.lint.per-file-ignores]
+"*/tests/*" = ["S101"]