feat: add Mermaid diagrams, transition tables, and __format__ support

- Add MermaidRenderer that converts DiagramGraph IR to Mermaid
  stateDiagram-v2 source (compound, parallel, history, guards, etc.)
- Add TransitionTableRenderer for markdown and RST table output
- Add MermaidGraphMachine facade mirroring DotGraphMachine
- Add __format__ to StateChart and StateMachineMetaclass supporting
  dot, mermaid, md/markdown, and rst format specs
- Extend CLI with --format option (mermaid, md, rst) and stdout support
- Add :format: option to Sphinx statemachine-diagram directive with
  sphinxcontrib-mermaid integration
- Update docs with new sections and doctests

Author: fgmacedo

docs/conf.py

@@ -52,6 +52,7 @@
     "sphinx_gallery.gen_gallery",
     "sphinx_copybutton",
     "statemachine.contrib.diagram.sphinx_ext",
+    "sphinxcontrib.mermaid",
 ]
 
 autosectionlabel_prefix_document = True

docs/diagram.md

@@ -110,6 +110,118 @@ send events before rendering:
 python -m statemachine.contrib.diagram tests.examples.traffic_light_machine.TrafficLightMachine diagram.png --events cycle cycle cycle
 ```
 
+Use `--format` to produce **Mermaid source** or a **transition table** instead
+of a Graphviz image:
+
+```bash
+# Mermaid stateDiagram-v2
+python -m statemachine.contrib.diagram tests.examples.traffic_light_machine.TrafficLightMachine output.mmd --format mermaid
+
+# Markdown transition table
+python -m statemachine.contrib.diagram tests.examples.traffic_light_machine.TrafficLightMachine output.md --format md
+
+# RST transition table
+python -m statemachine.contrib.diagram tests.examples.traffic_light_machine.TrafficLightMachine output.rst --format rst
+```
+
+Use `-` as the output file to write to stdout (handy for piping):
+
+```bash
+python -m statemachine.contrib.diagram tests.examples.traffic_light_machine.TrafficLightMachine - --format mermaid
+```
+
+
+## Text representations with `format()`
+
+State machines support Python's built-in `format()` protocol for quick text
+output — no diagram imports needed:
+
+```py
+>>> from tests.examples.traffic_light_machine import TrafficLightMachine
+>>> sm = TrafficLightMachine()
+>>> print(f"{sm:mermaid}")
+stateDiagram-v2
+    direction LR
+    state "Green" as green
+    state "Yellow" as yellow
+    state "Red" as red
+    [*] --> green
+    green --> yellow : cycle
+    yellow --> red : cycle
+    red --> green : cycle
+<BLANKLINE>
+    classDef active fill:#40E0D0,stroke:#333
+    green:::active
+<BLANKLINE>
+
+>>> print(f"{sm:md}")
+| State  | Event | Guard | Target |
+| ------ | ----- | ----- | ------ |
+| Green  | cycle |       | Yellow |
+| Yellow | cycle |       | Red    |
+| Red    | cycle |       | Green  |
+<BLANKLINE>
+
+```
+
+Works on **classes** too (no active-state highlighting):
+
+```py
+>>> print(f"{TrafficLightMachine:mermaid}")
+stateDiagram-v2
+    direction LR
+    state "Green" as green
+    state "Yellow" as yellow
+    state "Red" as red
+    [*] --> green
+    green --> yellow : cycle
+    yellow --> red : cycle
+    red --> green : cycle
+<BLANKLINE>
+
+```
+
+Supported format specs: `dot`, `mermaid`, `md` (or `markdown`), `rst`.
+An empty spec falls back to `repr()`.
+
+The `dot` format returns the Graphviz DOT language source (same output as
+`sm._graph().to_string()`):
+
+```py
+>>> print(f"{sm:dot}")  # doctest: +ELLIPSIS
+digraph TrafficLightMachine {
+...
+}
+
+```
+
+
+## Mermaid output
+
+The `MermaidGraphMachine` facade generates
+[Mermaid `stateDiagram-v2`](https://mermaid.js.org/syntax/stateDiagram.html)
+source text from any state machine — no external dependencies required:
+
+```py
+>>> from statemachine.contrib.diagram import MermaidGraphMachine
+>>> from tests.examples.traffic_light_machine import TrafficLightMachine
+>>> print(MermaidGraphMachine(TrafficLightMachine).get_mermaid())
+stateDiagram-v2
+    direction LR
+    state "Green" as green
+    state "Yellow" as yellow
+    state "Red" as red
+    [*] --> green
+    green --> yellow : cycle
+    yellow --> red : cycle
+    red --> green : cycle
+<BLANKLINE>
+
+```
+
+Compound states, parallel regions, history pseudo-states, guards, and
+active-state highlighting are all supported.
+
 
 ## Sphinx directive
 
@@ -190,6 +302,11 @@ The directive supports the same layout options as the standard `image` and
 : Events to send in sequence. When present, the machine is instantiated and
   each event is sent before rendering.
 
+`:format:` *(string)*
+: Output format. Use `mermaid` to render via
+  [sphinxcontrib-mermaid](https://github.com/mgaitan/sphinxcontrib-mermaid)
+  instead of Graphviz SVG. Default: DOT/SVG.
+
 **Image/figure options:**
 
 `:caption:` *(string)*

docs/releases/3.1.0.md

@@ -56,6 +56,25 @@ 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.
 
+
+### 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.
+
+Three ways to use it:
+
+- **`format()` / f-strings:** `f"{sm:mermaid}"`, `f"{sm:md}"`, `f"{sm:rst}"` —
+  works on both instances and classes.
+- **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.
+
+
 ### Bugfixes in 3.1.0
 
 - Fixes silent misuse of `Event()` with multiple positional arguments. Passing more than one

pyproject.toml

@@ -52,6 +52,7 @@ dev = [
     "sphinx-autobuild; python_version >'3.8'",
     "furo >=2024.5.6; python_version >'3.8'",
     "sphinx-copybutton >=0.5.2; python_version >'3.8'",
+    "sphinxcontrib-mermaid; python_version >'3.8'",
     "pdbr>=0.8.9; python_version >'3.8'",
     "babel >=2.16.0; python_version >='3.8'",
     "pytest-xdist>=3.6.1",

statemachine/contrib/diagram/__init__.py

@@ -5,6 +5,8 @@
 from .extract import extract
 from .renderers.dot import DotRenderer
 from .renderers.dot import DotRendererConfig
+from .renderers.mermaid import MermaidRenderer
+from .renderers.mermaid import MermaidRendererConfig
 
 
 class DotGraphMachine:
@@ -56,6 +58,32 @@ def __call__(self):
         return self.get_graph()
 
 
+class MermaidGraphMachine:
+    """Facade for generating Mermaid stateDiagram-v2 source from a state machine."""
+
+    direction = "LR"
+    active_fill = "#40E0D0"
+    active_stroke = "#333"
+
+    def __init__(self, machine):
+        self.machine = machine
+
+    def _build_config(self) -> MermaidRendererConfig:
+        return MermaidRendererConfig(
+            direction=self.direction,
+            active_fill=self.active_fill,
+            active_stroke=self.active_stroke,
+        )
+
+    def get_mermaid(self) -> str:
+        ir = extract(self.machine)
+        renderer = MermaidRenderer(config=self._build_config())
+        return renderer.render(ir)
+
+    def __call__(self) -> str:
+        return self.get_mermaid()
+
+
 def quickchart_write_svg(sm, path: str):
     """
     If the default dependency of GraphViz installed locally doesn't work for you. As an option,
@@ -135,7 +163,7 @@ def import_sm(qualname):
     return smclass
 
 
-def write_image(qualname, out, events=None):
+def write_image(qualname, out, events=None, fmt=None):
     """
     Given a `qualname`, that is the fully qualified dotted path to a StateMachine
     classes, imports the class and generates a dot graph using the `pydot` lib.
@@ -146,7 +174,13 @@ def write_image(qualname, out, events=None):
 
     If `events` is provided, the machine is instantiated and each event is sent
     before rendering, so the diagram highlights the current active state.
+
+    If `fmt` is provided, it overrides the output format: ``"mermaid"`` writes
+    Mermaid source text, ``"md"``/``"rst"`` write a transition table.
+    Use ``out="-"`` to write to stdout.
     """
+    import sys
+
     smclass = import_sm(qualname)
 
     if events:
@@ -156,9 +190,27 @@ def write_image(qualname, out, events=None):
     else:
         machine = smclass
 
-    graph = DotGraphMachine(machine).get_graph()
-    out_extension = out.rsplit(".", 1)[1]
-    graph.write(out, format=out_extension)
+    if fmt in ("mermaid", "md", "rst"):
+        if fmt == "mermaid":
+            text = MermaidGraphMachine(machine).get_mermaid()
+        else:
+            from .renderers.table import TransitionTableRenderer
+
+            ir = extract(machine)
+            text = TransitionTableRenderer().render(ir, fmt=fmt)
+
+        if out == "-":
+            sys.stdout.write(text)
+        else:
+            with open(out, "w") as f:
+                f.write(text)
+    else:
+        graph = DotGraphMachine(machine).get_graph()
+        if out == "-":
+            sys.stdout.buffer.write(graph.create_svg())  # type: ignore[attr-defined]
+        else:
+            out_extension = out.rsplit(".", 1)[1]
+            graph.write(out, format=out_extension)
 
 
 def main(argv=None):
@@ -180,6 +232,12 @@ def main(argv=None):
         nargs="+",
         help="Instantiate the machine and send these events before rendering.",
     )
+    parser.add_argument(
+        "--format",
+        choices=["mermaid", "md", "rst"],
+        default=None,
+        help="Output format: mermaid source, markdown table, or RST table.",
+    )
 
     args = parser.parse_args(argv)
-    write_image(qualname=args.class_path, out=args.out, events=args.events)
+    write_image(qualname=args.class_path, out=args.out, events=args.events, fmt=args.format)