From dfdc217dd1c6f6188a26848a295fde4191de9f66 Mon Sep 17 00:00:00 2001
From: Pranjal Bhatia <233476158+pranjalbhatia710@users.noreply.github.com>
Date: Sun, 31 May 2026 11:50:57 +0400
Subject: [PATCH] docs: explain selector chaining

---
 doc/selectors.rst | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/doc/selectors.rst b/doc/selectors.rst
index 323826cd0..29b56513e 100644
--- a/doc/selectors.rst
+++ b/doc/selectors.rst
@@ -52,6 +52,26 @@ Much more complex expressions are possible as well:
         .chamfer(0.1)
     )
 
+Selector methods can also be chained. Each selector operates on the current
+selection, so chaining is useful when an expression is easier to read as a
+sequence of narrowing steps. For example, ``faces(">Y").edges("%CIRCLE")`` first
+selects the positive Y face and then selects only the circular edges belonging to
+that face:
+
+.. cadquery::
+
+    result = (
+        cq.Workplane("XY")
+        .box(4, 4, 1)
+        .faces(">Z")
+        .workplane()
+        .rarray(2, 2, 2, 2)
+        .hole(0.5)
+        .faces(">Z")
+        .edges("%CIRCLE")
+        .chamfer(0.08)
+    )
+
 .. _filteringfaces:
 
 Filtering Faces