docs: revise 3.1.0 release notes and fix broken cross-references

Author: fgmacedo

docs/diagram.md

@@ -164,6 +164,7 @@ digraph TrafficLightMachine {
 An empty format spec (e.g., `f"{sm:}"`) falls back to `repr()`.
 
 
+(formatter-api)=
 ### Using the `formatter` API
 
 The `formatter` object is the programmatic entry point for rendering

docs/releases/3.1.0.md

@@ -4,75 +4,65 @@
 
 ## 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.
+### Text representations with `format()`
 
-Add `"statemachine.contrib.diagram.sphinx_ext"` to your `conf.py`
-extensions, then use the directive in any MyST Markdown page:
+State machines now support Python's built-in `format()` protocol. Use f-strings
+or `format()` to get text representations — on both classes and instances:
 
-````markdown
-```{statemachine-diagram} myproject.machines.OrderControl
-:events: receive_payment
-:caption: After payment
-:target:
+```python
+f"{TrafficLightMachine:md}"
+f"{sm:mermaid}"
+format(sm, "rst")
 ```
-````
 
-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).
+Supported formats:
 
-Using `:target:` without a value makes the diagram clickable, opening the
-full SVG in a new browser tab for zooming — useful for large statecharts.
+| Format    | Output                    | Requires              |
+|-----------|---------------------------|-----------------------|
+| `dot`     | Graphviz DOT source       | `pydot`               |
+| `svg`     | SVG markup (via Graphviz) | `pydot` + `graphviz`  |
+| `mermaid` | Mermaid stateDiagram-v2   | —                     |
+| `md`      | Markdown transition table | —                     |
+| `rst`     | RST transition table      | —                     |
 
-See {ref}`diagram:Sphinx directive` for full documentation.
-[#589](https://github.com/fgmacedo/python-statemachine/pull/589).
+See {ref}`diagram:Text representations` for details.
 
 
-### Performance: 5x–7x faster event processing
-
-The engine's hot paths have been systematically profiled and optimized, resulting in
-**4.7x–7.7x faster event throughput** and **1.9x–2.6x faster setup** across all
-machine types. All optimizations are internal — no public API changes.
-See [#592](https://github.com/fgmacedo/python-statemachine/pull/592) for details.
+### Formatter facade
 
+A new `Formatter` facade with decorator-based registration unifies all text
+format rendering behind a single API. Adding a new format requires only
+registering a render function — no changes to `__format__`, the CLI, or the
+Sphinx directive:
 
-### Thread safety documentation
-
-The sync engine is thread-safe: multiple threads can send events to the same state
-machine instance concurrently. This is now documented in the
-{ref}`processing model <thread-safety>` and verified by stress tests.
-[#592](https://github.com/fgmacedo/python-statemachine/pull/592).
+```python
+from statemachine.contrib.diagram import formatter
 
+formatter.render(sm, "mermaid")
+formatter.supported_formats()
 
-### Diagram CLI `--events` option
+@formatter.register_format("custom")
+def _render_custom(machine_or_class):
+    ...
+```
 
-The `python -m statemachine.contrib.diagram` command now accepts `--events` to
-instantiate the machine and send events before rendering, highlighting the
-current active state — matching the Sphinx directive's `:events:` option.
-See {ref}`diagram:Command line` for details.
+See {ref}`formatter-api` for details.
 
 
 ### Mermaid diagram support
 
 State machines can now be rendered as
 [Mermaid `stateDiagram-v2`](https://mermaid.js.org/syntax/stateDiagram.html)
-source text — no Graphviz installation required.
+source text — no Graphviz installation required. Supports compound states,
+parallel regions, history states, guards, and active-state highlighting.
 
 Three ways to use it:
 
-- **`format()` / f-strings:** `f"{sm:mermaid}"`, `f"{sm:md}"`, `f"{sm:rst}"` —
-  works on both instances and classes.
+- **f-strings:** `f"{sm:mermaid}"`
 - **CLI:** `python -m statemachine.contrib.diagram MyMachine - --format mermaid`
 - **Sphinx directive:** `:format: mermaid` renders via `sphinxcontrib-mermaid`.
 
-A new `TransitionTableRenderer` produces markdown or RST transition tables
-from the same diagram IR. See {ref}`diagram:Text representations with format()`
-and {ref}`diagram:Mermaid output` for details.
+See {ref}`diagram:Mermaid format` for details.
 
 
 ### Auto-expanding docstrings
@@ -94,13 +84,76 @@ class TrafficLight(StateChart):
 ```
 
 Any registered format works: `md`, `rst`, `mermaid`, `dot`, etc.
+Works with Sphinx autodoc — the expanded docstring is what gets rendered.
 See {ref}`diagram:Auto-expanding docstrings` for details.
 
 
+### 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.
+
+The `:format: mermaid` option renders via `sphinxcontrib-mermaid` instead of
+Graphviz.
+
+See {ref}`diagram:Sphinx directive` for full documentation.
+[#589](https://github.com/fgmacedo/python-statemachine/pull/589).
+
+
+### Diagram CLI `--events` and `--format` options
+
+The `python -m statemachine.contrib.diagram` command now accepts:
+
+- `--events` to instantiate the machine and send events before rendering,
+  highlighting the current active state.
+- `--format` to choose the output format (`mermaid`, `md`, `rst`, `dot`, `svg`,
+  or image formats via Graphviz). Use `-` as the output path to write text
+  formats to stdout.
+
+See {ref}`diagram:Command line` for details.
+[#593](https://github.com/fgmacedo/python-statemachine/pull/593).
+
+
+### Performance: 5x–7x faster event processing
+
+The engine's hot paths have been systematically profiled and optimized, resulting in
+**4.7x–7.7x faster event throughput** and **1.9x–2.6x faster setup** across all
+machine types. All optimizations are internal — no public API changes.
+See [#592](https://github.com/fgmacedo/python-statemachine/pull/592) for details.
+
+
+### Thread safety documentation
+
+The sync engine is thread-safe: multiple threads can send events to the same state
+machine instance concurrently. This is now documented in the
+{ref}`processing model <thread-safety>` and verified by stress tests.
+[#592](https://github.com/fgmacedo/python-statemachine/pull/592).
+
+
 ### Bugfixes in 3.1.0
 
 - Fixes silent misuse of `Event()` with multiple positional arguments. Passing more than one
-  transition to `Event()` (e.g., `Event(t1, t2)`) now raises {ref}`InvalidDefinition` with a
+  transition to `Event()` (e.g., `Event(t1, t2)`) now raises `InvalidDefinition` with a
   clear message suggesting the `|` operator. Previously, the second argument was silently
   interpreted as the event `id`, leaving the extra transitions eventless (auto-firing).
   [#588](https://github.com/fgmacedo/python-statemachine/pull/588).