[docs] clarify checkpoint semantics for trio.open_nursery (#3011)

* clarify checkpoint semantics for trio.open_nursery

* clarify what schedule-but-no-cancellation-point means for nurseries

Author: jakkdl

docs/source/reference-core.rst

@@ -102,6 +102,8 @@ them. Here are the rules:
     only that one will act as a checkpoint. This is documented
     on a case-by-case basis.
 
+    * :func:`trio.open_nursery` is a further exception to this rule.
+
 * Third-party async functions / iterators / context managers can act
   as checkpoints; if you see ``await <something>`` or one of its
   friends, then that *might* be a checkpoint. So to be safe, you

src/trio/_core/_run.py

@@ -986,7 +986,11 @@ def open_nursery(
     new `Nursery`.
 
     It does not block on entry; on exit it blocks until all child tasks
-    have exited.
+    have exited. If no child tasks are running on exit, it will insert a
+    schedule point (but no cancellation point) - equivalent to
+    :func:`trio.lowlevel.cancel_shielded_checkpoint`. This means a nursery
+    is never the source of a cancellation exception, it only propagates it
+    from sub-tasks.
 
     Args:
       strict_exception_groups (bool): Unless set to False, even a single raised exception