do stuff

photon-lib/py/docs/_stubs/wpimath/__init__.py

@@ -0,0 +1,5 @@
+# Minimal wpimath stub for Sphinx docs build
+from . import geometry
+from . import units
+
+__all__ = ["geometry", "units"]

photon-lib/py/docs/_stubs/wpimath/_init__wpimath.py

@@ -0,0 +1,4 @@
+# Stub module to match wpimath compiled module names
+# This file exists so imports like `wpimath._init__wpimath` succeed during docs build.
+
+# no-op

photon-lib/py/docs/_stubs/wpimath/geometry.py

@@ -0,0 +1,130 @@
+# Minimal geometry stubs for Sphinx documentation
+
+class Rotation3d:
+    def __init__(self, roll=0.0, pitch=0.0, yaw=0.0):
+        # store yaw as the primary rotation for simple stubs
+        self.roll = roll
+        self.pitch = pitch
+        self.yaw = yaw
+
+    def toRotation2d(self):
+        # convert yaw to a Rotation2d for simple compatibility in docs build
+        return Rotation2d(self.yaw)
+
+class Translation3d:
+    def __init__(self, x=0.0, y=0.0, z=0.0):
+        # Support both (x, y, z) and (distance, Rotation3d) forms used by the real wpimath
+        # If y is a Rotation3d, compute a point at 'distance' along its yaw/pitch
+        try:
+            from math import cos, sin
+        except Exception:
+            def cos(x):
+                return x
+            def sin(x):
+                return x
+
+        if hasattr(y, "yaw") and hasattr(y, "pitch"):
+            # interpret constructor as Translation3d(distance, Rotation3d)
+            distance = float(x)
+            pitch = float(getattr(y, "pitch", 0.0))
+            yaw = float(getattr(y, "yaw", 0.0))
+            # approximate spherical -> cartesian
+            self._x = distance * cos(pitch) * cos(yaw)
+            self._y = distance * cos(pitch) * sin(yaw)
+            self._z = distance * sin(pitch)
+        else:
+            self._x = float(x)
+            self._y = float(y)
+            self._z = float(z)
+
+    def X(self):
+        return self._x
+
+    def Y(self):
+        return self._y
+
+    def Z(self):
+        return self._z
+
+class Pose3d:
+    def __init__(self, *args, **kwargs):
+        pass
+
+class Rotation2d:
+    def __init__(self, *args):
+        # Accept several initialization forms used in the real wpimath Rotation2d
+        # - Rotation2d(angle)
+        # - Rotation2d(fx, xOffset) used by SimCameraProperties.getPixelYaw
+        if len(args) == 0:
+            self._angle = 0.0
+        elif len(args) == 1:
+            self._angle = float(args[0])
+        else:
+            # fallback: when called with fx, xOffset, approximate angle as 0.0
+            self._angle = 0.0
+
+    def degrees(self):
+        from math import degrees
+
+        return degrees(self._angle)
+
+    def radians(self):
+        return float(self._angle)
+    
+    def __add__(self, other):
+        # allow Rotation2d + Rotation2d or Rotation2d + numeric
+        if hasattr(other, "_angle"):
+            return Rotation2d(self._angle + float(other._angle))
+        try:
+            return Rotation2d(self._angle + float(other))
+        except Exception:
+            return NotImplemented
+
+    def __radd__(self, other):
+        # numeric + Rotation2d
+        return self.__add__(other)
+
+    def __sub__(self, other):
+        if hasattr(other, "_angle"):
+            return Rotation2d(self._angle - float(other._angle))
+        try:
+            return Rotation2d(self._angle - float(other))
+        except Exception:
+            return NotImplemented
+
+    def __neg__(self):
+        return Rotation2d(-self._angle)
+
+    def __repr__(self):
+        return f"Rotation2d({self._angle})"
+
+class Translation2d:
+    def __init__(self, x=0.0, y=0.0):
+        self._x = float(x)
+        self._y = float(y)
+
+    def X(self):
+        return self._x
+
+    def Y(self):
+        return self._y
+
+class Pose2d:
+    def __init__(self, *args, **kwargs):
+        pass
+
+    def __repr__(self) -> str:
+        return "Pose2d()"
+
+
+class Transform3d:
+    def __init__(self, *args, **kwargs):
+        pass
+
+
+class Quaternion:
+    def __init__(self, *args, **kwargs):
+        pass
+
+# Expose names commonly used by photonlibpy
+__all__ = ["Rotation3d", "Translation3d", "Pose3d", "Rotation2d", "Translation2d", "Pose2d"]

photon-lib/py/docs/_stubs/wpimath/interpolation.py

@@ -0,0 +1,12 @@
+# Minimal interpolation stub for docs
+class TimeInterpolatableRotation2dBuffer:
+    def __init__(self, *args, **kwargs):
+        pass
+
+    def addSample(self, *args, **kwargs):
+        pass
+
+    def sample(self, *args, **kwargs):
+        return None
+
+__all__ = ["TimeInterpolatableRotation2dBuffer"]

photon-lib/py/docs/_stubs/wpimath/interpolation/__init__.py

@@ -0,0 +1,3 @@
+from ._interpolation import *
+
+__all__ = ["TimeInterpolatableRotation2dBuffer"]

photon-lib/py/docs/_stubs/wpimath/interpolation/_interpolation.py

@@ -0,0 +1,25 @@
+# Minimal interpolation submodule stub for docs
+class TimeInterpolatableRotation2dBuffer:
+    def __init__(self, *args, **kwargs):
+        pass
+
+    def addSample(self, *args, **kwargs):
+        pass
+
+    def sample(self, *args, **kwargs):
+        return None
+
+
+class TimeInterpolatablePose3dBuffer:
+    def __init__(self, *args, **kwargs):
+        # buffer of Pose3d-like objects for docs import
+        pass
+
+    def addSample(self, *args, **kwargs):
+        pass
+
+    def sample(self, *args, **kwargs):
+        return None
+
+
+__all__ = ["TimeInterpolatableRotation2dBuffer", "TimeInterpolatablePose3dBuffer"]

photon-lib/py/docs/_stubs/wpimath/units.py

@@ -0,0 +1,31 @@
+"""Minimal wpimath.units stub for documentation builds."""
+
+def degreesToRadians(deg: float) -> float:
+    from math import pi
+
+    return deg * (pi / 180.0)
+
+
+# Represent seconds as a float alias for annotations
+seconds = float
+
+__all__ = ["degreesToRadians", "seconds"]
+
+# Common unit aliases used in type annotations in WPILib stubs
+meters = float
+meters_per_second = float
+meters_per_second_squared = float
+kilograms = float
+kilogram_square_meters = float
+
+__all__.extend([
+    "meters",
+    "meters_per_second",
+    "meters_per_second_squared",
+    "kilograms",
+    "kilogram_square_meters",
+    "hertz",
+])
+
+# frequency
+hertz = float

photon-lib/py/docs/source/conf.py

@@ -28,10 +28,20 @@ extensions = [
 import os
 import sys
 
+sys.path.insert(
+    0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "_stubs"))
+)  # add docs stubs first so they shadow unavailable third-party packages
+
 sys.path.insert(
     0, os.path.abspath("../../photonlibpy")
 )  # adjust based on your project layout
-print(sys.path)
+# Mock imports that aren't available in the docs build environment so autodoc
+# can import the local modules even if optional runtime deps (like wpimath)
+# aren't installed. Add other names here if you see warnings for missing
+# third-party packages during the build.
+autodoc_mock_imports = [
+    "wpilib",
+]
 templates_path = ["_templates"]
 exclude_patterns = []
 

photon-lib/py/docs/source/index.rst

@@ -4,7 +4,7 @@
    contain the root `toctree` directive.
 
 PhotonLib Python Documentation
-==========================
+===============================
 
 
 The main documentation for PhotonVision can be found at `photonvision.org <https://photonvision.org>`_.
@@ -14,4 +14,4 @@ The main documentation for PhotonVision can be found at `photonvision.org <https
    :caption: Contents:
 
    modules
-   photonlibpy  # if you have these .rst files from sphinx-apidoc
+   photonlibpy