Merge pull request #1143 from jwagenet/doc-fixes

Documentation: Formatting corrections and code style fixes

docs/assets/ttt/ttt-ppp0106.py

@@ -21,8 +21,8 @@ with BuildSketch(Location((0, -r1, y3))) as sk_body:
         m3 = IntersectingLine(m2 @ 1, m2 % 1, c1)
         m4 = Line(m3 @ 1, (r1, r1))
         m5 = JernArc(m4 @ 1, m4 % 1, r1, -90)
-        m6 = Line(m5 @ 1, m1 @ 0)
+        mirror(about=Plane.YZ)
-    mirror(make_face(l.line), Plane.YZ)
+    make_face()
     fillet(sk_body.vertices().group_by(Axis.Y)[1], 12)
     with Locations((x1 / 2, y_tot - 10), (-x1 / 2, y_tot - 10)):
         Circle(r2, mode=Mode.SUBTRACT)

docs/location_arithmetic.rst

@@ -3,7 +3,6 @@
 Location arithmetic for algebra mode
 ======================================
 
-
 Position a shape relative to the XY plane
 ---------------------------------------------
 
@@ -19,35 +18,33 @@ For the following use the helper function:
         circle = Circle(scale * .8).edge()
         return (triad + circle).locate(plane.location)
 
-
 1. **Positioning at a location**
 
     .. code-block:: build123d
 
-        loc = Location((0.1, 0.2, 0.3), (10, 20, 30))
+    loc = Location((0.1, 0.2, 0.3), (10, 20, 30))
 
-        face = loc * Rectangle(1,2)
+    face = loc * Rectangle(1, 2)
 
-        show_object(face, name="face")
+    show_object(face, name="face")
-        show_object(location_symbol(loc), name="location")
+    show_object(location_symbol(loc), name="location")
 
-    .. image:: assets/location-example-01.png
+.. image:: assets/location-example-01.png
 
 2) **Positioning on a plane**
 
     .. code-block:: build123d
 
-        plane = Plane.XZ
+    plane = Plane.XZ
 
-        face = plane * Rectangle(1, 2)
+    face = plane * Rectangle(1, 2)
 
-        show_object(face, name="face")
+    show_object(face, name="face")
-        show_object(plane_symbol(plane), name="plane")
+    show_object(plane_symbol(plane), name="plane")
 
-    .. image:: assets/location-example-07.png
+.. image:: assets/location-example-07.png
-
-    Note that the ``x``-axis and the ``y``-axis of the plane are on the ``x``-axis and the ``z``-axis of the world coordinate system (red and blue axis)
 
+Note: The ``x``-axis and the ``y``-axis of the plane are on the ``x``-axis and the ``z``-axis of the world coordinate system (red and blue axis).
 
 Relative positioning to a plane
 ------------------------------------
@@ -56,97 +53,96 @@ Relative positioning to a plane
 
     .. code-block:: build123d
 
-        loc = Location((0.1, 0.2, 0.3), (10, 20, 30))
+    loc = Location((0.1, 0.2, 0.3), (10, 20, 30))
 
-        face = loc * Rectangle(1,2)
+    face = loc * Rectangle(1,2)
 
-        box = Plane(loc) * Pos(0.2, 0.4, 0.1) * Box(0.2, 0.2, 0.2)
+    box = Plane(loc) * Pos(0.2, 0.4, 0.1) * Box(0.2, 0.2, 0.2)
-        # box = Plane(face.location) * Pos(0.2, 0.4, 0.1) * Box(0.2, 0.2, 0.2)
+    # box = Plane(face.location) * Pos(0.2, 0.4, 0.1) * Box(0.2, 0.2, 0.2)
-        # box = loc * Pos(0.2, 0.4, 0.1) * Box(0.2, 0.2, 0.2)
+    # box = loc * Pos(0.2, 0.4, 0.1) * Box(0.2, 0.2, 0.2)
 
-        show_object(face, name="face")
+    show_object(face, name="face")
-        show_object(location_symbol(loc), name="location")
+    show_object(location_symbol(loc), name="location")
-        show_object(box, name="box")
+    show_object(box, name="box")
 
-    .. image:: assets/location-example-02.png
+.. image:: assets/location-example-02.png
 
-    The ``x``, ``y``, ``z`` components of ``Pos(0.2, 0.4, 0.1)`` are relative to the ``x``-axis, ``y``-axis or
+The ``X``, ``Y``, ``Z`` components of ``Pos(0.2, 0.4, 0.1)`` are relative to the ``x``-axis, ``y``-axis or
-    ``z``-axis of the underlying location ``loc``.
+``z``-axis of the underlying location ``loc``.
 
-    Note: ``Plane(loc) *``, ``Plane(face.location) *`` and ``loc *`` are equivalent in this example.
+Note: ``Plane(loc) *``, ``Plane(face.location) *`` and ``loc *`` are equivalent in this example.
 
 2. **Rotate an object on a plane relative to the plane**
 
     .. code-block:: build123d
 
-        loc = Location((0.1, 0.2, 0.3), (10, 20, 30))
+    loc = Location((0.1, 0.2, 0.3), (10, 20, 30))
 
-        face = loc * Rectangle(1,2)
+    face = loc * Rectangle(1,2)
 
-        box = Plane(loc) * Rot(z=80) * Box(0.2, 0.2, 0.2)
+    box = Plane(loc) * Rot(Z=80) * Box(0.2, 0.2, 0.2)
 
-        show_object(face, name="face")
+    show_object(face, name="face")
-        show_object(location_symbol(loc), name="location")
+    show_object(location_symbol(loc), name="location")
-        show_object(box, name="box")
+    show_object(box, name="box")
 
-    .. image:: assets/location-example-03.png
+.. image:: assets/location-example-03.png
 
-    The box is rotated via ``Rot(z=80)`` around the ``z``-axis of the underlying location
+The box is rotated via ``Rot(Z=80)`` around the ``z``-axis of the underlying location
-    (and not of the z-axis of the world).
+(and not of the z-axis of the world).
 
-    More general:
+More general:
 
     .. code-block:: build123d
 
-        loc = Location((0.1, 0.2, 0.3), (10, 20, 30))
+    loc = Location((0.1, 0.2, 0.3), (10, 20, 30))
 
-        face = loc * Rectangle(1,2)
+    face = loc * Rectangle(1,2)
 
-        box = loc * Rot(20, 40, 80) * Box(0.2, 0.2, 0.2)
+    box = loc * Rot(20, 40, 80) * Box(0.2, 0.2, 0.2)
 
-        show_object(face, name="face")
+    show_object(face, name="face")
-        show_object(location_symbol(loc), name="location")
+    show_object(location_symbol(loc), name="location")
-        show_object(box, name="box")
+    show_object(box, name="box")
 
-    .. image:: assets/location-example-04.png
+.. image:: assets/location-example-04.png
 
-    The box is rotated via ``Rot(20, 40, 80)`` around all three axes relative to the plane.
+The box is rotated via ``Rot(20, 40, 80)`` around all three axes relative to the plane.
 
 3. **Rotate and position an object relative to a location**
 
     .. code-block:: build123d
 
-        loc = Location((0.1, 0.2, 0.3), (10, 20, 30))
+    loc = Location((0.1, 0.2, 0.3), (10, 20, 30))
 
-        face = loc * Rectangle(1,2)
+    face = loc * Rectangle(1,2)
 
-        box = loc *  Rot(20, 40, 80) * Pos(0.2, 0.4, 0.1) * Box(0.2, 0.2, 0.2)
+    box = loc * Rot(20, 40, 80) * Pos(0.2, 0.4, 0.1) * Box(0.2, 0.2, 0.2)
 
-        show_object(face, name="face")
+    show_object(face, name="face")
-        show_object(location_symbol(loc), name="location")
+    show_object(location_symbol(loc), name="location")
-        show_object(box, name="box")
+    show_object(box, name="box")
-        show_object(location_symbol(loc *  Rot(20, 40, 80), 0.5), options={"color":(0, 255, 255)}, name="local_location")
+    show_object(location_symbol(loc * Rot(20, 40, 80), 0.5), options={"color":(0, 255, 255)}, name="local_location")
 
-    .. image:: assets/location-example-05.png
+.. image:: assets/location-example-05.png
 
-    The box is positioned via ``Pos(0.2, 0.4, 0.1)`` relative to the location ``loc *  Rot(20, 40, 80)``
+The box is positioned via ``Pos(0.2, 0.4, 0.1)`` relative to the location ``loc * Rot(20, 40, 80)``
 
 4. **Position and rotate an object relative to a location**
 
     .. code-block:: build123d
 
-        loc = Location((0.1, 0.2, 0.3), (10, 20, 30))
+    loc = Location((0.1, 0.2, 0.3), (10, 20, 30))
 
-        face = loc * Rectangle(1,2)
+    face = loc * Rectangle(1,2)
 
-        box = loc * Pos(0.2, 0.4, 0.1) * Rot(20, 40, 80) * Box(0.2, 0.2, 0.2)
+    box = loc * Pos(0.2, 0.4, 0.1) * Rot(20, 40, 80) * Box(0.2, 0.2, 0.2)
 
-        show_object(face, name="face")
+    show_object(face, name="face")
-        show_object(location_symbol(loc), name="location")
+    show_object(location_symbol(loc), name="location")
-        show_object(box, name="box")
+    show_object(box, name="box")
-        show_object(location_symbol(loc * Pos(0.2, 0.4, 0.1), 0.5), options={"color":(0, 255, 255)}, name="local_location")
+    show_object(location_symbol(loc * Pos(0.2, 0.4, 0.1), 0.5), options={"color":(0, 255, 255)}, name="local_location")
 
-    .. image:: assets/location-example-06.png
+.. image:: assets/location-example-06.png
-
-    Note: This is the same as `box = loc * Location((0.2, 0.4, 0.1), (20, 40, 80)) * Box(0.2, 0.2, 0.2)`
 
+Note: This is the same as ``box = loc * Location((0.2, 0.4, 0.1), (20, 40, 80)) * Box(0.2, 0.2, 0.2)``

docs/tutorial_surface_heart_token.rst

@@ -20,7 +20,7 @@ the object. To illustrate this process, we will create the following game token:
 Useful :class:`~topology.Face` creation methods include
 :meth:`~topology.Face.make_surface`, :meth:`~topology.Face.make_bezier_surface`,
 and :meth:`~topology.Face.make_surface_from_array_of_points`. See the
-:doc:`surface_modeling` overview for the full list.
+:doc:`tutorial_surface_modeling` overview for the full list.
 
 In this case, we'll use the ``make_surface`` method, providing it with the edges that define
 the perimeter of the surface and a central point on that surface.
@@ -128,5 +128,5 @@ from the heart.
 Next steps
 ----------
 
-Continue to :doc:`tutorial_heart_token` for an advanced example using
+Continue to :doc:`tutorial_spitfire_wing_gordon` for an advanced example using
 :meth:`~topology.Face.make_gordon_surface` to create a Supermarine Spitfire wing.

src/build123d/topology/one_d.py

@@ -547,7 +547,7 @@ class Mixin1D(Shape[TOPODS]):
 
         A curvature comb is a set of short line segments (“teeth”) erected
         perpendicular to the curve that visualize the signed curvature κ(u).
-        Tooth length is proportional to |κ| and the direction encodes the sign
+        Tooth length is proportional to \|κ\| and the direction encodes the sign
         (left normal for κ>0, right normal for κ<0). This is useful for inspecting
         fairness and continuity (C0/C1/C2) of edges and wires.
 
@@ -570,7 +570,7 @@ class Mixin1D(Shape[TOPODS]):
             - On straight segments, κ = 0 so no teeth are drawn.
             - At inflection points κ→0 and the tooth flips direction.
             - At C0 corners the tangent is discontinuous; nearby teeth may jump.
-            C1 yields continuous direction; C2 yields continuous magnitude as well.
+              C1 yields continuous direction; C2 yields continuous magnitude as well.
 
         Example:
             >>> comb = my_wire.curvature_comb(count=200, max_tooth_size=2.0)
@@ -1097,16 +1097,16 @@ class Mixin1D(Shape[TOPODS]):
         The meaning of the returned parameter depends on the type of self:
 
         - **Edge**: Returns the native OCCT curve parameter corresponding to the
-        given normalized `position` (0.0 → start, 1.0 → end). For closed/periodic
+          given normalized `position` (0.0 → start, 1.0 → end). For closed/periodic
-        edges, OCCT may return a value **outside** the edge's nominal parameter
+          edges, OCCT may return a value **outside** the edge's nominal parameter
-        range `[param_min, param_max]` (e.g., by adding/subtracting multiples of
+          range `[param_min, param_max]` (e.g., by adding/subtracting multiples of
-        the period). If you require a value folded into the edge's range, apply a
+          the period). If you require a value folded into the edge's range, apply a
-        modulo with the parameter span.
+          modulo with the parameter span.
 
         - **Wire**: Returns a *composite* parameter encoding both the edge index
-        and the position within that edge: the **integer part** is the zero-based
+          and the position within that edge: the **integer part** is the zero-based
-        count of fully traversed edges, and the **fractional part** is the
+          count of fully traversed edges, and the **fractional part** is the
-        normalized position in `[0.0, 1.0]` along the current edge.
+          normalized position in `[0.0, 1.0]` along the current edge.
 
         Args:
             position (float): Normalized arc-length position along the shape,