docs: replace inline diagram generation with statemachine-diagram directive

Convert tutorial.md and transitions.md to use the directive instead of
doctest write_png + image references. Extract CoffeeOrder, OrderWorkflow,
and OrderWorkflowCompound to tests/machines/ for importability.

Add tip about Graphviz requirement and seealso linking to diagram.md
for deeper coverage (Sphinx directive, Jupyter, QuickChart, etc.).

Delete the 3 PNG files that are no longer referenced.

Author: fgmacedo

docs/images/transition_compound_cancel.png

@@ -171,16 +171,14 @@ True
 Compare the diagrams — both model the same behavior, but the compound version
 makes the "cancellable" grouping explicit in the hierarchy:
 
-```py
->>> getfixture("requires_dot_installed")
->>> OrderWorkflow()._graph().write_png("docs/images/transition_from_any.png")
->>> OrderWorkflowCompound()._graph().write_png("docs/images/transition_compound_cancel.png")
-
+```{statemachine-diagram} tests.machines.transition_from_any.OrderWorkflow
+:caption: from_.any()
 ```
 
-| `from_.any()` | Compound |
-|---|---|
-| ![from_.any()](images/transition_from_any.png) | ![Compound](images/transition_compound_cancel.png) |
+```{statemachine-diagram} tests.machines.transition_from_any.OrderWorkflowCompound
+:caption: Compound
+:target:
+```
 
 The compound approach scales better as you add more states — no need to
 remember to include each new state in a `from_()` list.

docs/images/transition_from_any.png

@@ -345,46 +345,36 @@ factories, and the full list of listener callbacks.
 
 ## Generating diagrams
 
-Visualize any state machine as a diagram. Install the `diagrams` extra
-first:
+Visualize any state machine as a diagram:
 
+```{statemachine-diagram} tests.machines.tutorial_coffee_order.CoffeeOrder
+:alt: CoffeeOrder diagram
 ```
-pip install python-statemachine[diagrams]
-```
-
-Then generate an image at runtime:
-
-```py
->>> getfixture("requires_dot_installed")
-
->>> from statemachine import StateChart, State
-
->>> class CoffeeOrder(StateChart):
-...     pending = State(initial=True)
-...     preparing = State()
-...     ready = State()
-...     picked_up = State(final=True)
-...
-...     start = pending.to(preparing)
-...     finish = preparing.to(ready)
-...     pick_up = ready.to(picked_up)
 
->>> order = CoffeeOrder()
->>> order._graph().write_png("docs/images/tutorial_coffeeorder.png")
+Generate diagrams programmatically with `_graph()`:
 
+```python
+order = CoffeeOrder()
+order._graph().write_png("order.png")
 ```
 
-![CoffeeOrder](images/tutorial_coffeeorder.png)
-
 Or from the command line:
 
 ```bash
 python -m statemachine.contrib.diagram my_module.CoffeeOrder order.png
 ```
 
+```{tip}
+Diagram generation requires [Graphviz](https://graphviz.org/) (`dot` command)
+and the `diagrams` extra:
+
+    pip install python-statemachine[diagrams]
+```
+
 ```{seealso}
-See [](diagram.md) for Jupyter integration, SVG output, DPI settings, and
-the `quickchart_write_svg` alternative that doesn't require Graphviz.
+See [](diagram.md) for highlighting active states, Jupyter integration,
+SVG output, DPI settings, Sphinx directive, and the `quickchart_write_svg`
+alternative that doesn't require Graphviz.
 ```
 
 

docs/images/tutorial_coffeeorder.png

@@ -0,0 +1,30 @@
+from statemachine import State
+from statemachine import StateChart
+
+
+class OrderWorkflow(StateChart):
+    pending = State(initial=True)
+    processing = State()
+    done = State()
+    completed = State(final=True)
+    cancelled = State(final=True)
+
+    process = pending.to(processing)
+    complete = processing.to(done)
+    finish = done.to(completed)
+    cancel = cancelled.from_.any()
+
+
+class OrderWorkflowCompound(StateChart):
+    class active(State.Compound):
+        pending = State(initial=True)
+        processing = State()
+        done = State(final=True)
+
+        process = pending.to(processing)
+        complete = processing.to(done)
+
+    completed = State(final=True)
+    cancelled = State(final=True)
+    done_state_active = active.to(completed)
+    cancel = active.to(cancelled)

docs/transitions.md

@@ -0,0 +1,13 @@
+from statemachine import State
+from statemachine import StateChart
+
+
+class CoffeeOrder(StateChart):
+    pending = State(initial=True)
+    preparing = State()
+    ready = State()
+    picked_up = State(final=True)
+
+    start = pending.to(preparing)
+    finish = preparing.to(ready)
+    pick_up = ready.to(picked_up)