docs: polish the 3.2.2 release notes and the pages they link to

Open the notes with a summary and a list of the behavior changes to check
when upgrading, group the fixes by theme, and cite the issue and the PR of
every entry. Add the missing entries for #650 and the GraphvizError
exception change, the rejection of nested callbacks named like an event,
and the events dropped after a top-level final state.

Document Event(delay=..., internal=...) in the events page, the declared
delay in the delayed events section, and the queue being discarded on
termination in the processing model.

Signed-off-by: Fernando Macedo <fgmacedo@gmail.com>

Author: fgmacedo

docs/diagram.md

@@ -460,7 +460,8 @@ The directive supports the same layout options as the standard `image` and
 `:target:` *(URL or empty)*
 : Makes the diagram clickable. When set without a value, the raw SVG is
   saved as a file and linked so users can open it in a new tab for
-  full-resolution zooming — useful for large or complex diagrams.
+  full-resolution zooming, useful for large or complex diagrams. The link is relative to
+  the page, so it also works when the documentation is served below a URL prefix.
 
 `:class:` *(space-separated strings)*
 : Extra CSS classes for the wrapper element.
@@ -486,6 +487,8 @@ JupyterLab cells — no extra code needed:
 ![Approval machine on JupyterLab](images/lab_approval_machine_accepted.png)
 
 
+(diagram-graphviz-errors)=
+
 ## When Graphviz fails
 
 Every path that runs `dot` (the `svg` format, `_repr_svg_()` in Jupyter, the command line
@@ -496,10 +499,11 @@ what Graphviz wrote to stderr, such as
 `Error: <stdin>: syntax error in line 25 near ','`. The Sphinx directive reports the same
 text as a build warning.
 
-A missing program raises {class}`~statemachine.contrib.diagram.GraphvizNotFoundError`, a
-subclass of both `GraphvizError` and {class}`FileNotFoundError`. Catch `GraphvizError` to
-handle every case; code that skips diagrams with `except FileNotFoundError` when Graphviz is
-not installed keeps working:
+`GraphvizError` is a {class}`~statemachine.exceptions.StateMachineError`. A missing program
+raises {class}`~statemachine.contrib.diagram.GraphvizNotFoundError`, a subclass of both
+`GraphvizError` and {class}`FileNotFoundError`. Catch `GraphvizError` to handle every case;
+code that skips diagrams with `except FileNotFoundError` when Graphviz is not installed keeps
+working:
 
 ```py
 >>> from statemachine.contrib.diagram import GraphvizError

docs/events.md

@@ -71,6 +71,28 @@ human-readable display name, use the `Event` class explicitly:
 
 ```
 
+`Event` also takes a `delay`, in milliseconds, and `internal`. Both apply by default every
+time the event is triggered, and an explicit argument to `send()` overrides either one
+(`delay=0`, `internal=False`). A delayed event waits in the external queue until it is due (see
+{ref}`delayed-events`), and an internal event triggered from a callback runs within the
+current macrostep (see {ref}`processing model`). An event cannot be both delayed and
+internal: declaring it so raises {class}`~statemachine.exceptions.InvalidDefinition`.
+
+```py
+>>> class Lantern(StateChart):
+...     dark = State(initial=True)
+...     lit = State(final=True)
+...
+...     light = Event(dark.to(lit), delay=50)
+
+>>> Lantern.light.delay
+50
+
+```
+
+Each of these forms also declares an event inside a `State.Compound` or `State.Parallel`
+body (see {ref}`compound-states`).
+
 
 (event-identity)=
 

docs/processing_model.md

@@ -71,7 +71,9 @@ Within a single macrostep, the engine repeats:
 3. If neither step produced a transition, the macrostep is **done**.
 
 After the macrostep completes, the engine picks the next event from the
-**external queue** (placed by `send()`) and starts a new macrostep.
+**external queue** (placed by `send()`) and starts a new macrostep. Once the
+machine reaches a top-level final state it stops, and the events left in the
+external queue are discarded.
 
 
 ### Event queues