Jrm/docs test

pyproject.toml

@@ -13,6 +13,10 @@ dependencies = [
     "deprecated>=1.2.15",
     "gql[requests,websockets]>=3.5.0",
     "httpx>=0.28.1",
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.6.5",
+    "mkdocstrings>=0.28.1",
+    "mkdocstrings-python>=1.15.0",
     "pydantic>=2.10.5",
     "pydantic-settings>=2.7.1",
     "stringcase>=1.2.0",

src/docs/Specklepy_SDK/api/client.md

@@ -0,0 +1 @@
+::: specklepy.api.client.SpeckleClient

src/docs/Specklepy_SDK/objects/Data_Objects/DataObject.md

@@ -0,0 +1 @@
+::: specklepy.objects.data_objects.DataObject

src/docs/Specklepy_SDK/objects/Data_Objects/QgisObject.md

@@ -0,0 +1 @@
+::: specklepy.objects.data_objects.QgisObject

src/docs/Specklepy_SDK/objects/Interfaces/IBlenderObject.md

@@ -0,0 +1 @@
+::: specklepy.objects.interfaces.IBlenderObject

src/docs/Specklepy_SDK/objects/Interfaces/ICurve.md

@@ -0,0 +1 @@
+::: specklepy.objects.interfaces.ICurve

src/docs/Specklepy_SDK/objects/Interfaces/IDataObject.md

@@ -0,0 +1 @@
+::: specklepy.objects.interfaces.IDataObject

src/docs/Specklepy_SDK/objects/Interfaces/IDisplayValue.md

@@ -0,0 +1 @@
+::: specklepy.objects.interfaces.IDisplayValue

src/docs/Specklepy_SDK/objects/Interfaces/IGisObject.md

@@ -0,0 +1 @@
+::: specklepy.objects.interfaces.IBlenderObject

src/docs/Specklepy_SDK/objects/Interfaces/IHasArea.md

@@ -0,0 +1 @@
+::: specklepy.objects.interfaces.IHasArea

src/docs/Specklepy_SDK/objects/Interfaces/IHasUnits.md

@@ -0,0 +1 @@
+::: specklepy.objects.interfaces.IHasUnits

src/docs/Specklepy_SDK/objects/Interfaces/IHasVolume.md

@@ -0,0 +1 @@
+::: specklepy.objects.interfaces.IHasVolume

src/docs/Specklepy_SDK/objects/Interfaces/IProperties.md

@@ -0,0 +1 @@
+::: specklepy.objects.interfaces.IProperties

src/docs/Specklepy_SDK/objects/Other/RenderMaterial.md

@@ -0,0 +1 @@
+::: specklepy.objects.other.RenderMaterial

src/docs/Specklepy_SDK/objects/Primitve/Interval.md

@@ -0,0 +1 @@
+::: specklepy.objects.primitive.Interval

src/docs/Specklepy_SDK/objects/Proxies/ColorProxy.md

@@ -0,0 +1 @@
+::: specklepy.objects.proxies.ColorProxy

src/docs/Specklepy_SDK/objects/Proxies/GroupProxy.md

@@ -0,0 +1 @@
+::: specklepy.objects.proxies.GroupProxy

src/docs/Specklepy_SDK/objects/Proxies/InstanceDefinitionProxy.md

@@ -0,0 +1 @@
+::: specklepy.objects.proxies.InstanceDefinitionProxy

src/docs/Specklepy_SDK/objects/Proxies/InstanceProxy.md

@@ -0,0 +1 @@
+::: specklepy.objects.proxies.InstanceProxy

src/docs/Specklepy_SDK/objects/Proxies/RenderMaterialProxy.md

@@ -0,0 +1 @@
+::: specklepy.objects.proxies.RenderMaterialProxy

src/docs/Specklepy_SDK/objects/base.md

@@ -0,0 +1 @@
+::: specklepy.objects.base.Base

src/docs/Specklepy_SDK/objects/geometry/Arc.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.arc.Arc

src/docs/Specklepy_SDK/objects/geometry/Box.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.box.Box

src/docs/Specklepy_SDK/objects/geometry/Circle.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.circle.Circle

src/docs/Specklepy_SDK/objects/geometry/ControlPoint.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.control_point.ControlPoint

src/docs/Specklepy_SDK/objects/geometry/Ellipse.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.ellipse.Ellipse

src/docs/Specklepy_SDK/objects/geometry/Line.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.line.Line

src/docs/Specklepy_SDK/objects/geometry/Mesh.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.mesh.Mesh

src/docs/Specklepy_SDK/objects/geometry/Plane.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.plane.Plane

src/docs/Specklepy_SDK/objects/geometry/Point.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.point.Point

src/docs/Specklepy_SDK/objects/geometry/Point_Cloud.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.point_cloud.PointCloud

src/docs/Specklepy_SDK/objects/geometry/Polycurve.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.polycurve.Polycurve

src/docs/Specklepy_SDK/objects/geometry/Polyline.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.polyline.Polyline

src/docs/Specklepy_SDK/objects/geometry/Spiral.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.spiral.Spiral

src/docs/Specklepy_SDK/objects/geometry/Surface.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.surface.Surface

src/docs/Specklepy_SDK/objects/geometry/Vector.md

@@ -0,0 +1 @@
+::: specklepy.objects.geometry.vector.Vector

src/docs/index.md

@@ -0,0 +1,29 @@
+# Introduction
+
+Welcome to the Specklepy Developer Docs - a single source of documentation on everything Specklepy! If you're looking for info on how to use Speckle, check our [user guide](https://speckle.guide/).
+
+### Code Repository
+The Python SDK can be found in our [repository](//github.com/specklesystems/specklepy), its readme contains instructions on how to build it.
+
+### Installation
+You can install it using pip
+```
+pip install specklepy
+```
+
+### Key Components
+
+SpecklePy has three main parts:
+
+1. a `SpeckleClient` which allows you to interact with the server API
+2. `operations` and `transports` for sending and receiving large objects
+3. a `Base` object and accompaniying serializer for creating and customizing your own Speckle objects
+
+
+### Local Data Paths
+
+It may be helpful to know where the local accounts and object cache dbs are stored. Depending on on your OS, you can find the dbs at:
+
+- Windows: `APPDATA` or `<USER>\AppData\Roaming\Speckle`
+- Linux: `$XDG_DATA_HOME` or by default `~/.local/share/Speckle`
+- Mac: `~/.config/Speckle`

src/docs/speckle_automate/automate_context.md

@@ -0,0 +1 @@
+::: speckle_automate.automation_context.AutomationContext

src/mkdocs.yml

@@ -0,0 +1,64 @@
+site_name: Specklepy Docs
+theme:
+  name: material
+  favicon: assets/speckle_logo.png
+  logo: assets/speckle_logo.png
+  features:
+    - navigation.tabs
+  palette:
+    # Palette toggle for light mode
+    - scheme: default
+      primary: white
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - scheme: slate
+      primary: black
+      logo: assets/logo_white.png
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+
+
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+
+extra_css:
+- css/mkdocstrings.css
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [.]
+          options:
+            parameter_headings: false
+            members_order: source
+            separate_signature: true
+            filters: ["!^_"] #Ignore _ prefixed properties
+            docstring_options:
+              ignore_init_summary: true
+            merge_init_into_class: true
+            show_signature_annotations: true
+            signature_crossrefs: true
+            show_if_no_docstring: true
+            show_labels: true
+            show_source: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            show_bases: false
+            heading_level: 3
+
+          inventories:
+            - url: https://docs.python.org/3/objects.inv
+              domains: [py, std]

src/specklepy/objects/base.py

@@ -323,6 +323,30 @@ def _validate_type(t: Optional[type], value: Any) -> Tuple[bool, Any]:
 
 @dataclass(kw_only=True)
 class Base(_RegisteringBase, speckle_type="Base"):
+    """Base class for all Speckle objects.
+
+    The base object class is the foundation of all data being
+    transferred with Speckle. Any custom data structure that you want to transfer via
+    Speckle should inherit from it.
+
+    Objects in Speckle are immutable for storage purposes. When any property changes,
+    the object gets a new identity (hash). This hash is stored in the `id` property
+    after serialization.
+
+    Attributes:
+        id: Unique identifier (hash) for the object. This is typically
+        set automatically during serialization and depends on the object's properties.
+        applicationId: Optional identifier for the application that created
+            this object, can store the host application's native object ID.
+
+    ```py title="Example"
+    from specklepy.objects.base import Base
+    obj = Base(id="some-id", applicationId="my-app")
+    obj["custom_prop"] = 42  # Add a dynamic property
+    obj["@detached_prop"] = another_object  # Add a detached property
+    ```
+    """
+
     id: Union[str, None] = None
     # totalChildrenCount: Union[int, None] = None
     applicationId: Union[str, None] = None

src/specklepy/objects/data_objects.py

@@ -13,6 +13,10 @@ class DataObject(
     speckle_type="Objects.Data.DataObject",
     detachable={"displayValue"},
 ):
+    """
+    A generic data object that can hold arbitrary properties and display values.
+    """
+
     name: str
     properties: Dict[str, object]
     displayValue: List[Base]

src/specklepy/objects/geometry/arc.py

@@ -9,17 +9,51 @@
 
 @dataclass(kw_only=True)
 class Arc(Base, IHasUnits, ICurve, speckle_type="Objects.Geometry.Arc"):
+    """
+    An arc defined by a plane, start point, mid point and end point.
+
+    This class represents a circular arc in 3D space, defined by three points
+    and a plane. The arc is a portion of a circle that lies on the specified plane.
+
+    Attributes:
+        plane: The plane on which the arc lies
+        startPoint: The starting point of the arc
+        midPoint: A point on the arc between the start and end points
+        endPoint: The ending point of the arc.
+
+
+    ```py title="Example"
+    from specklepy.objects.geometry.plane import Plane
+    from specklepy.objects.geometry.point import Point
+    plane = Plane(origin=Point(0, 0, 0), normal=Point(0, 0, 1))
+    start = Point(1, 0, 0)
+    mid = Point(0.7071, 0.7071, 0)
+    end = Point(0, 1, 0)
+    arc = Arc(plane=plane, startPoint=start, midPoint=mid, endPoint=end)
+    ```
+    """
+
     plane: Plane
     startPoint: Point
     midPoint: Point
     endPoint: Point
 
     @property
     def radius(self) -> float:
+        """Calculates the radius of the arc.
+
+        Returns:
+            The radius of the arc, as the distance from the start point to the origin.
+        """
         return self.startPoint.distance_to(self.plane.origin)
 
     @property
     def length(self) -> float:
+        """Calculates the length of the arc.
+
+        Returns:
+            The length of the arc.
+        """
         start_to_mid = self.startPoint.distance_to(self.midPoint)
         mid_to_end = self.midPoint.distance_to(self.endPoint)
         r = self.radius
@@ -30,6 +64,11 @@ def length(self) -> float:
 
     @property
     def measure(self) -> float:
+        """Calculates the angular measure of the arc in radians.
+
+        Returns:
+            The angular measure of the arc in radians.
+        """
         start_to_mid = self.startPoint.distance_to(self.midPoint)
         mid_to_end = self.midPoint.distance_to(self.endPoint)
         r = self.radius

src/specklepy/objects/geometry/box.py

@@ -9,7 +9,29 @@
 @dataclass(kw_only=True)
 class Box(Base, IHasUnits, IHasArea, IHasVolume, speckle_type="Objects.Geometry.Box"):
     """
-    a 3-dimensional box oriented on a plane
+    A 3-dimensional box oriented on a plane.
+
+    This class represents a rectangular prism in 3D space, defined by a base plane and
+    three intervals specifying its dimensions along the x, y, and z axes.
+
+    Attributes:
+        basePlane: The plane on which the box is oriented
+        xSize: The interval defining the box's size along the x-axis
+        ySize: The interval defining the box's size along the y-axis
+        zSize: The interval defining the box's size along the z-axis
+
+    ```py title="Example"
+    from specklepy.objects.geometry.plane import Plane
+    from specklepy.objects.geometry.point import Point
+    from specklepy.objects.primitive import Interval
+
+    base_plane = Plane(origin=Point(0, 0, 0), normal=Point(0, 0, 1))
+    x_size = Interval(start=0, end=10)
+    y_size = Interval(start=0, end=5)
+    z_size = Interval(start=0, end=3)
+
+    box = Box(basePlane=base_plane, xSize=x_size, ySize=y_size, zSize=z_size)
+    ```
     """
 
     basePlane: Plane
@@ -29,6 +51,11 @@ def __repr__(self) -> str:
 
     @property
     def area(self) -> float:
+        """Calculates the surface area of the box.
+
+        Returns:
+            The total surface area of the box.
+        """
         return 2 * (
             self.xSize.length * self.ySize.length
             + self.xSize.length * self.zSize.length
@@ -37,4 +64,9 @@ def area(self) -> float:
 
     @property
     def volume(self) -> float:
+        """Calculates the volume of the box.
+
+        Returns:
+            The volume of the box.
+        """
         return self.xSize.length * self.ySize.length * self.zSize.length