Added docs for new extrude capabilities (#894)

* Added docs for new extrude capabilities

Added examples for extrude and cutblind until extrusion parameter

Updated weird leftover text in Example page

* added note on relative axis coords for Workplane.revolve

* added mixed extrude cutblind example

cadquery/cq.py

@@ -2993,7 +2993,7 @@ def extrude(
           to the normal of the plane. The string "next" extrudes until the next face orthogonal to
           the wire normal. "last" extrudes to the last face. If a object of type Face is passed then
           the extrusion will extend until this face.
-        :param boolean combine: True to combine the resulting solid with parent solids if found.
+        :param boolean combine: True to combine the resulting solid with parent solids if found. (Cannot be set to False when `until` is not set as a float)
         :param boolean clean: call :py:meth:`clean` afterwards to have a clean shape
         :param boolean both: extrude in both directions symmetrically
         :param float taper: angle for optional tapered extrusion
@@ -3070,6 +3070,12 @@ def revolve(
         *  if combine is False, the new value is pushed onto the stack.
         *  if combine is true, the value is combined with the context solid if it exists,
            and the resulting solid becomes the new context solid.
+
+        .. note::
+            Keep in mind that `axisStart` and `axisEnd` are defined relative to the current Workplane center position.
+            So if for example you want to revolve a circle centered at (10,0,0) around the Y axis, be sure to either :py:meth:`move` (or :py:meth:`moveTo`)
+            the current Workplane position or specify `axisStart` and `axisEnd` with the correct vector position.
+            In this example (0,0,0), (0,1,0) as axis coords would fail.
         """
         # Make sure we account for users specifying angles larger than 360 degrees
         angleDegrees %= 360.0

doc/examples.rst

@@ -13,20 +13,19 @@ They are organized from simple to complex, so working through them in order is t
 Each example lists the API elements used in the example for easy reference.
 Items introduced in the example are marked with a **!**
 
-.. note::
-
-    You may want to work through these examples by pasting the text into a code editor in a CadQuery .
-    If you do, make sure to take these steps so that they work:
 
-       1. paste the content into the build() method, properly indented, and
-       2. add the line 'return result' at the end. The samples below are autogenerated, but they use a different
-          syntax than the models on the website need to be.
 
 .. note::
 
     We strongly recommend installing `CQ-editor <https://github.com/CadQuery/CQ-editor>`_,
     so that you can work along with these examples interactively. See :ref:`installation` for more info.
 
+    If you do, make sure to take these steps so that they work:
+
+       1. import cadquery as cq
+       2. add the line ``show_object(result)``  at the end. The samples below are autogenerated, but they use a different
+          syntax than the models on the website need to be.
+
 .. warning::
 
     * You have to have an svg capable browser to view these!
@@ -622,6 +621,124 @@ and a circular section.
         * :py:meth:`Workplane.circle`
         * :py:meth:`Workplane.rect`
 
+Extruding until a given face
+--------------------------------------------
+
+Sometimes you will want to extrude a wire until a given face that can be not planar or where you
+might not know easily the distance you have to extrude to. In such cases you can use `next`, `last`
+or even give a :class:`~cadquery.Face` object for the `until` argument of
+:meth:`~cadquery.Workplane.extrude`.
+
+
+.. cadquery::
+
+    result = (cq.Workplane(origin = (20,0,0))
+        .circle(2)
+        .revolve(180, (-20,0,0),(-20,-1,0))
+        .center(-20,0)
+        .workplane()
+        .rect(20,4)
+        .extrude("next")
+    )
+
+The same behaviour is available with :meth:`~cadquery.Workplane.cutBlind` and as you can see it is
+also possible to work on several :class:`~cadquery.Wire` objects at a time (the
+same is true for :meth:`~cadquery.Workplane.extrude`).
+
+.. cadquery::
+
+    skycrappers_locations = [(-16,1),(-8,0),(7,0.2),(17,-1.2)]
+    angles = iter([15,0,-8,10])
+    skycrappers = (cq.Workplane()
+        .pushPoints(skycrappers_locations)
+        .eachpoint(lambda loc: (cq.Workplane()
+                                .rect(5,16)
+                                .workplane(offset=10)
+                                .ellipse(3,8)
+                                .workplane(offset=10)
+                                .slot2D(20,5, 90)
+                                .loft()
+                                .rotateAboutCenter((0,0,1),next(angles))
+                                .val().located(loc)
+                                )
+        )    
+    )
+
+    result = (skycrappers
+        .transformed((0,-90,0))
+        .moveTo(15,0)
+        .rect(3,3, forConstruction=True)
+        .vertices()
+        .circle(1)    
+        .cutBlind("last")
+    )
+
+Here is a typical situation where extruding and cuting until a given surface is very handy. It allows us to extrude or cut until a curved surface without overlapping issues.
+
+.. cadquery::
+
+    import cadquery as cq
+
+    sphere = cq.Workplane().sphere(5)
+    base = (cq.Workplane(origin=(0,0,-2))
+        .box(12,12,10)
+        .cut(sphere)
+        .edges("|Z")
+        .fillet(2)
+    )
+    sphere_face = base.faces(">>X[2] and (not |Z) and (not |Y)").val()
+    base = (base
+        .faces("<Z")
+        .workplane()
+        .circle(2)
+        .extrude(10)
+    )
+
+    shaft = (cq.Workplane()
+        .sphere(4.5)
+        .circle(1.5)
+        .extrude(20)
+    )
+
+    spherical_joint = (base.union(shaft)
+        .faces(">X")
+        .workplane(centerOption="CenterOfMass")
+        .move(0,4)
+        .slot2D(10,2,90)
+        .cutBlind(sphere_face)    
+        .workplane(offset=10)
+        .move(0,2)
+        .circle(0.9)
+        .extrude("next")
+    )
+
+    result = spherical_joint
+
+.. warning::
+
+    If the wire you want to extrude cannot be fully projected on the target surface, the result will
+    be unpredictable. Furthermore the algorithm in charge of finding the candidates faces do it's
+    search by counting all the faces intersected by a line created from your wire center along your
+    extrusion direction. So make sure your wire can be projected on your target face to avoid
+    unexpected behaviour.
+
+.. topic:: Api References
+
+    .. hlist::
+        :columns: 3
+
+        * :py:meth:`Workplane.cutBlind` **!**
+        * :py:meth:`Workplane.rect`
+        * :py:meth:`Workplane.ellipse`
+        * :py:meth:`Workplane.workplane`
+        * :py:meth:`Workplane.slot2D`
+        * :py:meth:`Workplane.loft`
+        * :py:meth:`Workplane.rotateAboutCenter`
+        * :py:meth:`Workplane.transformed`
+        * :py:meth:`Workplane.moveTo`
+        * :py:meth:`Workplane.circle`
+
+
 Making Counter-bored and Counter-sunk Holes
 ----------------------------------------------
 

doc/roadmap.rst

@@ -83,6 +83,3 @@ primitive creation
         * cone
         * torus
         * wedge
-
-extrude/cut up to surface
-    allow a cut or extrude to terminate at another surface, rather than either through all or a fixed distance