Common unittests, removed VertexList

docs/advantages.rst

@@ -122,3 +122,4 @@ a fully custom selection:
 One can sort by all of the following attributes:
 
 .. autoclass:: build_common.SortBy
+    :noindex:

docs/key_concepts.rst

@@ -168,6 +168,57 @@ extrudes these pending faces into `Solid` objects. Likewise, `Loft` will take al
 
 Normally the user will not need to interact directly with pending objects.
 
+***********
+Shape Lists
+***********
+
+The builders include methods to extract Edges, Faces, Solids, or Vertices from the objects
+they are building.  These methods are as follows:
+
++-------------+---------+---------+----------+------------+
+| Size        |  Edges  |  Faces  |  Solids  |  Vertices  |
++=============+=========+=========+==========+============+
+| BuildLine   | edges() |         |          | vertices() |
++-------------+---------+---------+----------+------------+
+| BuildSketch | edges() | faces() |          | vertices() |
++-------------+---------+---------+----------+------------+
+| BuildPart   | edges() | edges() | solids() | vertices() |
++-------------+---------+---------+----------+------------+
+
+All of these methods return objects in a subclass of `list`, a `ShapeList` with some custom
+filtering and sorting methods predefined described as follows.
+
+.. autoclass:: build_common.ShapeList
+    :members:
+    :exclude-members: axis_map
+
+The filter and sort parameters use the following Enums (numeric values are meaningless):
+
+.. autoclass:: build_common.Axis
+    :members:
+
+.. autoclass:: build_common.SortBy
+    :members:
+
+.. autoclass:: build_common.Type
+    :members:
+
+
+It is important to note that standard list methods such as `sorted` or `filtered` can
+be used to easily build complex selectors beyond what is available with the predefined
+sorts and filters. Here is an example of a custom filters:
+
+.. code-block:: python
+
+    with BuildSketch() as din:
+        ...
+        outside_vertices = filter(
+            lambda v: (v.Y == 0.0 or v.Y == height)
+            and -overall_width / 2 < v.X < overall_width / 2,
+            din.vertices(),
+        )
+
+
 *************************************
 Multiple Work Planes - BuildPart Only
 *************************************