docs: add Sphinx directive release notes to 3.1.0

Author: fgmacedo

docs/releases/3.1.0.md

@@ -4,6 +4,35 @@
 
 ## What's new in 3.1.0
 
+### Sphinx directive for inline diagrams
+
+A new Sphinx extension renders state machine diagrams directly in your
+documentation from an importable class path — no manual image generation
+needed.
+
+Add `"statemachine.contrib.diagram.sphinx_ext"` to your `conf.py`
+extensions, then use the directive in any MyST Markdown page:
+
+````markdown
+```{statemachine-diagram} myproject.machines.OrderControl
+:events: receive_payment
+:caption: After payment
+:target:
+```
+````
+
+The directive supports the same options as the standard `image`/`figure`
+directives (`:width:`, `:height:`, `:scale:`, `:align:`, `:target:`,
+`:class:`, `:name:`), plus `:events:` to instantiate the machine and send
+events before rendering (highlighting the current state).
+
+Using `:target:` without a value makes the diagram clickable, opening the
+full SVG in a new browser tab for zooming — useful for large statecharts.
+
+See {ref}`diagram:Sphinx directive` for full documentation.
+[#589](https://github.com/fgmacedo/python-statemachine/pull/589).
+
+
 ### Bugfixes in 3.1.0
 
 - Fixes silent misuse of `Event()` with multiple positional arguments. Passing more than one