Merge pull request #921 from CadQuery/sketch-docs

Slight improvement of the sketch tutorial

Author: jmwright

cadquery/sketch.py

@@ -35,7 +35,7 @@
     arc_point,
 )
 
-Modes = Literal["a", "s", "i"]
+Modes = Literal["a", "s", "i", "c"]  # add, subtract, intersect, construct
 Point = Union[Vector, Tuple[Real, Real]]
 
 T = TypeVar("T", bound="Sketch")

doc/sketch.rst

@@ -25,17 +25,38 @@ combining them using boolean operations.
        cq.Sketch()
        .trapezoid(4,3,90)
        .vertices()
-       .circle(.5,mode='s')
+       .circle(.5, mode='s')
        .reset()
        .vertices()
        .fillet(.25)
        .reset()
-       .rarray(.6,1,5,1).slot(1.5,0.4,mode='s',angle=90)
+       .rarray(.6,1,5,1).slot(1.5,0.4, mode='s', angle=90)
     )
 
 Note that selectors are implemented, but selection has to be explicitly reset. Sketch
 class does not implement history and all modifications happen in-place.
 
+Modes
+^^^^^
+
+Every operation from the face API accepts a mode parameter to define how to combine the created object with existing ones. It can be fused (``mode='a'``), cut (``mode='s'``), intersected (``mode='i'``) or just stored for construction (``mode='c'``). In the last case, it is mandatory to specify a ``tag`` in order to be able to refer to the object later on. By default faces are fused together. Note the usage of the subtractive and additive modes in the example above. The additional two are demonstrated below.
+
+.. cadquery::
+    :height: 600px
+
+    result = (
+       cq.Sketch()
+       .rect(1, 2, mode='c', tag='base')
+       .vertices(tag='base')
+       .circle(.7)
+       .reset()
+       .edges('|Y', tag='base')
+       .ellipse(1.2, 1, mode='i')
+       .reset()
+       .rect(2, 2, mode='i')
+       .clean()
+    )
+
 
 Edge-based API
 ==============
@@ -62,6 +83,7 @@ If needed, one can construct sketches by placing individual edges.
 Once the construction is finished it has to be converted to the face-based representation
 using :meth:`~cadquery.Sketch.assemble`. Afterwards, face based operations can be applied.
 
+
 Convex hull
 ===========
 
@@ -269,4 +291,4 @@ Reusing of existing sketches is needed when using :meth:`~cadquery.Workplane.lof
         .loft()
         )
 
-When lofting only outer wires are taken into account.
+When lofting only outer wires are taken into account and inner wires are silently ignored.