add class and method references for hover

docs/introductory_examples.rst

@@ -21,7 +21,7 @@ They are organized from simple to complex, so working through them in order is t
 1. Simple Rectangular Plate
 ---------------------------------------------------
 
-Just about the simplest possible example, a rectangular box
+Just about the simplest possible example, a rectangular :class:`~build_part.Box`.
 
 .. image:: assets/general_ex1.svg
     :align: center
@@ -33,7 +33,9 @@ Just about the simplest possible example, a rectangular box
 2. Plate with Hole
 ---------------------------------------------------
 
-A rectangular box, but with a hole added. In this case we are using ``Mode.SUBTRACT`` to cut the Cylinder from the Box.
+A rectangular box, but with a hole added. In this case we are using 
+:class:`~build_enums.Mode` ``.SUBTRACT`` to cut the :class:`~build_part.Cylinder` 
+from the :class:`~build_part.Box`.
 
 .. image:: assets/general_ex2.svg
     :align: center
@@ -45,8 +47,9 @@ A rectangular box, but with a hole added. In this case we are using ``Mode.SUBTR
 3. An extruded prismatic solid
 ---------------------------------------------------
 
-Build a prismatic solid using extrusion. This time we can first create a 2D ``BuildSketch`` with a
+Build a prismatic solid using extrusion. This time we can first create a 2D 
-subtracted Rectangle and then use BuildPart's ``Extrude`` feature.
+:class:`~build_sketch.BuildSketch` with a subtracted Rectangle and then use 
+:class:`~build_part.BuildPart`'s :class:`~build_part.Extrude` feature.
 
 .. image:: assets/general_ex3.svg
     :align: center
@@ -58,11 +61,13 @@ subtracted Rectangle and then use BuildPart's ``Extrude`` feature.
 4. Building Profiles using lines and arcs
 ---------------------------------------------------
 
-Sometimes you need to build complex profiles using lines and arcs. This example builds a prismatic
+Sometimes you need to build complex profiles using lines and arcs. This example 
-solid from 2D operations. It is not necessary to create variables for the line segments, but it will 
+builds a prismatic solid from 2D operations. It is not necessary to create 
-be useful in a later example. BuildSketch operates on closed Faces, and the operation ``MakeFace`` is 
+variables for the line segments, but it will be useful in a later example. 
-used to convert the pending line segments from BuildLine into a closed Face. Note that to build a closed 
+:class:`~build_sketch.BuildSketch` operates on closed Faces, and the operation 
-face it requires line segments that form a closed shape.
+:class:`~build_sketch.MakeFace` is used to convert the pending line segments 
+from :class:`~build_line.BuildLine` into a closed Face. Note that to build a 
+closed face it requires line segments that form a closed shape.
 
 .. image:: assets/general_ex4.svg
     :align: center
@@ -74,7 +79,8 @@ face it requires line segments that form a closed shape.
 5. Moving the current working point
 ---------------------------------------------------
 
-Using ``Locations`` we can place one (or multiple) objects at one (or multiple) places.
+Using :class:`~build_common.Locations` we can place one (or multiple) objects 
+at one (or multiple) places.
 
 .. image:: assets/general_ex5.svg
     :align: center
@@ -86,8 +92,9 @@ Using ``Locations`` we can place one (or multiple) objects at one (or multiple)
 6. Using Point Lists
 ---------------------------------------------------
 
-Sometimes you need to create a number of features at various locations. You can use a list of
+Sometimes you need to create a number of features at various 
-points to construct multiple objects at once.
+:class:`~build_common.Locations`. You can use a list of points to construct 
+multiple objects at once.
 
 .. image:: assets/general_ex6.svg
     :align: center
@@ -99,7 +106,8 @@ points to construct multiple objects at once.
 7. Polygons
 ---------------------------------------------------
 
-You can create regular polygons for each stack point if you would like.
+You can create :class:`~build_sketch.RegularPolygon` for each stack point if 
+you would like.
 
 .. image:: assets/general_ex7.svg
     :align: center
@@ -111,8 +119,10 @@ You can create regular polygons for each stack point if you would like.
 8. Polylines
 ---------------------------------------------------
 
-``Polyline`` allows creating a shape from a large number of chained points connected by
+:class:`~build_line.Polyline` allows creating a shape from a large number 
-lines. This example uses a polyline to create one half of an i-beam shape, which is mirrored to create the final profile.
+of chained points connected by lines. This example uses a polyline to create 
+one half of an i-beam shape, which is :class:`~build_generic.Mirror` ed to 
+create the final profile.
 
 .. image:: assets/general_ex8.svg
     :align: center
@@ -124,13 +134,13 @@ lines. This example uses a polyline to create one half of an i-beam shape, which
 9. Selectors, Fillets, and Chamfers
 ---------------------------------------------------
 
-This example introduces multiple useful and important concepts. Firstly ``Chamfer`` 
+This example introduces multiple useful and important concepts. Firstly :class:`~build_generic.Chamfer` 
-and ``Fillet`` can be used to "bevel" and "round" edges respectively. Secondly, 
+and :class:`~build_generic.Fillet` can be used to "bevel" and "round" edges respectively. Secondly, 
 these two methods require an edge or a list of edges to operate on. To select all 
 edges, you could simply pass-in ``*ex9.edges()``. Note that the star (\*) unpacks 
 the list. 
 
-Note that ``group_by(Axis.Z)`` returns a list of lists of edges that is grouped by 
+Note that :meth:`~direct_api.ShapeList.group_by` ``(Axis.Z)`` returns a list of lists of edges that is grouped by 
 their z-position. In this case we want to use the ``[-1]`` group which, by 
 convention, will be the highest z-dimension group.
 
@@ -145,8 +155,8 @@ convention, will be the highest z-dimension group.
 10. Select Last and Hole
 ---------------------------------------------------
 
-Using ``Select.LAST`` you can select the most recently modified edges. It is used to perform a ``Fillet`` in
+Using :class:`~build_enums.Select` ``.LAST`` you can select the most recently modified edges. It is used to perform a :class:`~build_generic.Fillet` in
-this example. This example also makes use of ``Hole`` which automatically cuts through the entire part.
+this example. This example also makes use of :class:`~build_part.Hole` which automatically cuts through the entire part.
 
 .. image:: assets/general_ex10.svg
     :align: center
@@ -158,13 +168,13 @@ this example. This example also makes use of ``Hole`` which automatically cuts t
 11. Use a face as a plane for BuildSketch and introduce GridLocations
 ----------------------------------------------------------------------------
 
-``BuildSketch`` accepts a Plane or a Face, so in this case we locate the Sketch 
+:class:`~build_sketch.BuildSketch` accepts a Plane or a Face, so in this case we locate the Sketch 
 on the top of the part. Note that the face used as input to BuildSketch needs 
-to be Planar or unpredictable behavior can result. Additionally ``GridLocations`` 
+to be Planar or unpredictable behavior can result. Additionally :class:`~build_common.GridLocations` 
 can be used to create a grid of points that are simultaneously used to place 4 
 pentagons.
 
-Lastly, ``Extrude`` can be used with a negative amount and ``Mode.SUBTRACT`` to 
+Lastly, :class:`~build_part.Extrude` can be used with a negative amount and ``Mode.SUBTRACT`` to 
 cut these from the parent. Note that the direction implied by positive or negative 
 inputs to amount is relative to the normal direction of the face or plane. As a 
 result of this, unexpected behavior can occur if the extrude direction and mode 
@@ -195,7 +205,7 @@ The star (\*) operator is again used to unpack the list.
 13. CounterBoreHoles, CounterSinkHoles and PolarLocations
 -------------------------------------------------------------
 
-We use a face to establish a location for ``Workplanes``. ``PolarLocations`` creates a list of
+We use a face to establish a location for :class:`~build_common.Workplanes`. :class:`~build_common.PolarLocations` creates a list of
 points that are radially distributed.
 
 Counter-sink and counter-bore holes are useful for creating recessed areas for fasteners.
@@ -212,19 +222,19 @@ Counter-sink and counter-bore holes are useful for creating recessed areas for f
 ------------------------------------------------------------
 
 Build123d includes a feature for finding the position along a line segment. This 
-is normalized between 0 and 1 and can be accessed using the '\@' operator. 
+is normalized between 0 and 1 and can be accessed using the :meth:`~direct_api.Mixin1D.position_at` operator. 
-Similarly the '\%' operator returns the line direction at a given point.
+Similarly the :meth:`~direct_api.Mixin1D.tangent_at` operator returns the line direction at a given point.
 
 These two features are very powerful for chaining line segments together without 
 having to repeat dimensions again and again, which is error prone, time 
 consuming, and more difficult to maintain.
 
-It is also possible to use ``Vector`` addition (and other vector math operations) 
+It is also possible to use :class:`~direct_api.Vector` addition (and other vector math operations) 
 as seen in the ``l3`` variable.
 
-The ``Sweep`` method takes any pending faces and sweeps them through the provided 
+The :class:`~build_part.Sweep` method takes any pending faces and sweeps them through the provided 
 path (in this case the path is taken from the pending edges from ``ex14_ln``). 
-``Sweep`` requires a single connected wire. The pending faces must lie on the 
+:class:`~build_part.Revolve` requires a single connected wire. The pending faces must lie on the 
 path.
 
 .. image:: assets/general_ex14.svg
@@ -265,7 +275,7 @@ method shifts the plane in the normal direction (positive or negative).
 17. Mirroring From Faces
 ---------------------------------------------------
 
-Here we select the farthest face in the Y-direction and turn it into a ``Plane`` using the
+Here we select the farthest face in the Y-direction and turn it into a :class:`~direct_api.Plane` using the
 ``Plane()`` class.
 
 .. image:: assets/general_ex17.svg
@@ -291,12 +301,12 @@ with a negative distance and Mode.SUBTRACT to cut it out from the main body.
 19. Locating a Workplane on a vertex
 ---------------------------------------------------
 
-Here a face is selected and passed to ``Workplanes``, and two different strategies are used to select vertices.
+Here a face is selected and passed to :class:`~build_common.Workplanes`, and two different strategies are used to select vertices.
-Firstly ``vtx`` uses ``group_by`` and ``Axis.X`` to select a particular vertex. The second strategy uses a custom
+Firstly ``vtx`` uses :meth:`~direct_api.ShapeList.group_by` and ``Axis.X`` to select a particular vertex. The second strategy uses a custom
-defined Axis ``vtx2Axis`` that is pointing roughly in the direction of a vertex to select, and then ``sort_by``
+defined Axis ``vtx2Axis`` that is pointing roughly in the direction of a vertex to select, and then :meth:`~direct_api.ShapeList.sort_by` 
-this custom Axis. Then the X and Y positions of these vertices are selected and passed to ``Locations``
+this custom Axis. Then the X and Y positions of these vertices are selected and passed to :class:`~build_common.Locations`
-as the center points for a ``BuildSketch`` which is used to place two circles that cuts through the main part.
+as the center points for a :class:`~build_sketch.BuildSketch` which is used to place two circles that cuts through the main part.
-Note that if you passed the variable ``vtx`` directly to ``Locations`` then the part would be offset from
+Note that if you passed the variable ``vtx`` directly to :class:`~build_common.Locations` then the part would be offset from
 the Workplane by the vertex z-position.
 
 .. image:: assets/general_ex19.svg
@@ -336,9 +346,9 @@ positioning another cylinder perpendicular and halfway along the first.
 ---------------------------------------------------
 
 It is also possible to create a rotated workplane, building upon some of the concepts in an earlier
-example with the ``rotated()`` method.
+example with the :meth:`~direct_api.Plane.rotated` method.
 
-GridLocations places 4 Circles on 4 points on this rotated workplane, and then the Circles are
+:class:`~build_common.GridLocations` places 4 Circles on 4 points on this rotated workplane, and then the Circles are
 extruded in the "both" (positive and negative) normal direction.
 
 .. image:: assets/general_ex22.svg
@@ -351,8 +361,10 @@ extruded in the "both" (positive and negative) normal direction.
 23. Revolve
 ---------------------------------------------------
 
-Here we build a sketch with a Polyline, Line, and a Circle. It is absolutely critical that the sketch
+Here we build a sketch with a :class:`~build_line.Polyline`, 
-is only on one side of the axis of rotation before Revolve is called.
+:class:`~build_line.Line`, and a :class:`~build_sketch.Circle`. It is 
+absolutely critical that the sketch is only on one side of the axis of rotation 
+before Revolve is called.
 
 To that end, Split is used with Plane.ZY to keep only one side of the Sketch.
 
@@ -371,7 +383,7 @@ can be accomplished e.g. like this: ``show_object(ex23_sk.sketch)``.
 
 Loft is a very powerful tool that can be used to join dissimilar shapes. In this case we make a
 conical-like shape from a circle and a rectangle that is offset vertically. In this case 
-``Loft`` automatically takes the pending faces that were added by the two BuildSketches. 
+:class:`~build_part.Loft` automatically takes the pending faces that were added by the two BuildSketches. 
 Loft can behave unexpectedly when the input faces are not parallel to each other.
 
 .. image:: assets/general_ex24.svg
@@ -384,8 +396,8 @@ Loft can behave unexpectedly when the input faces are not parallel to each other
 25. Offset Sketch
 ---------------------------------------------------
 
-BuildSketch faces can be transformed with a 2D ``Offset``. They can be offset inwards or outwards,
+BuildSketch faces can be transformed with a 2D :class:`~build_generic.Offset`. They can be offset inwards or outwards,
-and with different techniques for extending the corners (see ``kind`` in the Offset docs).
+and with different techniques for extending the corners (see :class:`~build_enums.Kind` in the Offset docs).
 
 .. image:: assets/general_ex25.svg
     :align: center
@@ -398,9 +410,9 @@ and with different techniques for extending the corners (see ``kind`` in the Off
 ---------------------------------------------------
 
 BuildPart parts can also be transformed using an offset, but in this case with 
-a 3D ``Offset``. Also commonly known as a shell, this allows creating thin walls 
+a 3D :class:`~build_generic.Offset`. Also commonly known as a shell, this allows creating thin walls 
 using very few operations. This can also be offset inwards or outwards. Faces 
-can be selected to be "deleted" using the ``openings`` parameter of ``Offset``.
+can be selected to be "deleted" using the ``openings`` parameter of :class:`~build_generic.Offset`.
 
 Note that self intersecting edges and/or faces can break both 2D and 3D offsets.
 
@@ -455,8 +467,9 @@ the bottle opening.
 30. Bezier Curve
 ---------------------------------------------------
 
-Here ``pts`` is used as an input to both ``Polyline`` and ``Bezier`` and ``wts`` to Bezier alone.
+Here ``pts`` is used as an input to both :class:`~build_line.Polyline` and 
-These two together create a closed line that is made into a face and extruded.
+:class:`~build_line.Bezier` and ``wts`` to Bezier alone. These two together 
+create a closed line that is made into a face and extruded.
 
 .. image:: assets/general_ex30.svg
     :align: center
@@ -469,7 +482,8 @@ These two together create a closed line that is made into a face and extruded.
 ---------------------------------------------------
 
 Locations contexts can be nested to create groups of shapes. Here 24 triangles, 6 squares, and
-1 hexagon are created and then extruded. Notably ``PolarLocations`` rotates any "children" groups by default.
+1 hexagon are created and then extruded. Notably :class:`~build_common.PolarLocations` 
+rotates any "children" groups by default.
 
 .. image:: assets/general_ex31.svg
     :align: center
@@ -483,8 +497,8 @@ Locations contexts can be nested to create groups of shapes. Here 24 triangles,
 
 In this example, a standard python for-loop is used along with a list of faces extracted from a BuildSketch
 to progressively modify the extrusion amount. There are 7 faces in the BuildSketch, so this results in 7
-separate calls to ``Extrude``. ``Mode.PRIVATE`` is used in ``BuildSketch()`` to avoid adding these faces
+separate calls to :class:`~build_part.Extrude`. ``Mode.PRIVATE`` is used in :class:`~build_sketch.BuildSketch` 
-until the for-loop.
+to avoid adding these faces until the for-loop.
 
 .. image:: assets/general_ex32.svg
     :align: center
@@ -496,8 +510,9 @@ until the for-loop.
 33. Python Function and For-Loop
 ---------------------------------------------------
 
-Building on the previous example, a standard python function is used to return a BuildSketch as a function
+Building on the previous example, a standard python function is used to return 
-of several inputs to progressively modify the size of each square.
+a :class:`~build_sketch.BuildSketch` as a function of several inputs to 
+progressively modify the size of each square.
 
 .. image:: assets/general_ex33.svg
     :align: center
@@ -510,7 +525,7 @@ of several inputs to progressively modify the size of each square.
 ---------------------------------------------------
 
 The text "Hello" is placed on top of a rectangle and embossed (raised) by placing a BuildSketch on the
-top face (``topf``). Note that ``align`` is used to control the text placement. We re-use 
+top face (``topf``). Note that :class:`~build_enums.Align` is used to control the text placement. We re-use 
 the ``topf`` variable to select the same face and deboss (indented) the text "World". Note that if we simply
 ran ``BuildSketch(ex34.faces().sort_by(Axis.Z)[-1])`` for both ``ex34_sk1&2`` it would incorrectly locate
 the 2nd "World" text on the top of the "Hello" text.
@@ -525,8 +540,9 @@ the 2nd "World" text on the top of the "Hello" text.
 35. Slots
 ---------------------------------------------------
 
-Here we create a ``SlotCenterToCenter`` and then use a ``BuildLine`` and ``RadiusArc`` to create an
+Here we create a :class:`~build_sketch.SlotCenterToCenter` and then use a 
-arc for two instances of ``SlotArc``.
+:class:`~build_line.BuildLine` and :class:`~build_line.RadiusArc` to create an 
+arc for two instances of :class:`~build_sketch.SlotArc`.
 
 .. image:: assets/general_ex35.svg
     :align: center
@@ -538,8 +554,9 @@ arc for two instances of ``SlotArc``.
 36. Extrude Until
 ---------------------------------------------------
 
-Sometimes you will want to extrude until a given face that can be not planar or where you might
+Sometimes you will want to extrude until a given face that can be not planar or 
-not know easily the distance you have to extrude to. In such cases you can use ``Extrude`` until
+where you might not know easily the distance you have to extrude to. In such 
+cases you can use :class:`~build_part.Extrude` :class:`~build_enums.Until` 
 with ``Until.NEXT`` or ``Until.LAST``.
 
 .. image:: assets/general_ex36.svg