feat: auto-expand {statechart:FORMAT} placeholders in class docstrings

The metaclass now detects {statechart:FORMAT} placeholders in docstrings
and replaces them at class definition time with the rendered output.
The docstring always stays in sync with the actual states and transitions.

Any registered format works: md, rst, mermaid, dot, etc.
Indentation of the placeholder line is preserved in the output.

Author: fgmacedo

docs/diagram.md

@@ -181,7 +181,7 @@ stateDiagram-v2
 
 ```
 
-Supported format specs: `dot`, `mermaid`, `md` (or `markdown`), `rst`.
+Supported format specs: `dot`, `svg`, `mermaid`, `md` (or `markdown`), `rst`.
 An empty spec falls back to `repr()`.
 
 The `dot` format returns the Graphviz DOT language source (same output as
@@ -196,6 +196,71 @@ digraph TrafficLightMachine {
 ```
 
 
+## Auto-expanding docstrings
+
+Use `{statechart:FORMAT}` placeholders in your class docstring to embed
+a live representation of the state machine. The placeholder is replaced
+at class definition time, so the docstring always reflects the actual
+states and transitions:
+
+```py
+>>> from statemachine.statemachine import StateChart
+>>> from statemachine.state import State
+
+>>> class TrafficLight(StateChart):
+...     """A traffic light.
+...
+...     {statechart:md}
+...     """
+...     green = State(initial=True)
+...     yellow = State()
+...     red = State()
+...     cycle = green.to(yellow) | yellow.to(red) | red.to(green)
+
+>>> print(TrafficLight.__doc__)
+A traffic light.
+<BLANKLINE>
+| State  | Event | Guard | Target |
+| ------ | ----- | ----- | ------ |
+| Green  | cycle |       | Yellow |
+| Yellow | cycle |       | Red    |
+| Red    | cycle |       | Green  |
+<BLANKLINE>
+<BLANKLINE>
+
+```
+
+Any registered format works: `{statechart:rst}`, `{statechart:mermaid}`,
+`{statechart:dot}`, etc.
+
+### Choosing the right format
+
+| Context | Recommended format |
+|---------|-------------------|
+| Sphinx with RST (autodoc default) | `{statechart:rst}` |
+| Sphinx with MyST Markdown | `{statechart:md}` |
+| `help()` in terminal / IDE | Either works; `md` reads more cleanly |
+
+### Sphinx autodoc integration
+
+Since the placeholder is expanded at class definition time, Sphinx `autodoc`
+sees the final rendered text — no extra configuration needed.
+
+For example, this class uses `{statechart:rst}` in its docstring:
+
+```{literalinclude} ../tests/machines/showcase_simple.py
+:pyobject: SimpleSC
+:language: python
+```
+
+And here is the rendered autodoc output:
+
+```{eval-rst}
+.. autoclass:: tests.machines.showcase_simple.SimpleSC
+   :noindex:
+```
+
+
 ## Mermaid output
 
 The `MermaidGraphMachine` facade generates

docs/releases/3.1.0.md

@@ -75,6 +75,28 @@ from the same diagram IR. See {ref}`diagram:Text representations with format()`
 and {ref}`diagram:Mermaid output` for details.
 
 
+### Auto-expanding docstrings
+
+Use `{statechart:FORMAT}` placeholders in your class docstring to embed a
+live representation of the state machine. The placeholder is replaced at
+class definition time, so the docstring always stays in sync with the code:
+
+```python
+class TrafficLight(StateChart):
+    """A traffic light.
+
+    {statechart:md}
+    """
+    green = State(initial=True)
+    yellow = State()
+    red = State()
+    cycle = green.to(yellow) | yellow.to(red) | red.to(green)
+```
+
+Any registered format works: `md`, `rst`, `mermaid`, `dot`, etc.
+See {ref}`diagram:Auto-expanding docstrings` for details.
+
+
 ### Bugfixes in 3.1.0
 
 - Fixes silent misuse of `Event()` with multiple positional arguments. Passing more than one

statemachine/factory.py

@@ -1,3 +1,4 @@
+import re
 from typing import Any
 from typing import Dict
 from typing import List
@@ -91,6 +92,37 @@ def __init__(
 
         cls._check()
         cls._setup()
+        cls._expand_docstring()
+
+    _STATECHART_RE = re.compile(r"\{statechart:(\w+)\}")
+
+    def _expand_docstring(cls) -> None:
+        """Replace ``{statechart:FORMAT}`` placeholders in the class docstring."""
+        doc = cls.__doc__
+        if not doc:
+            return
+
+        from .contrib.diagram.formatter import formatter
+
+        def _replace(match: "re.Match[str]") -> str:
+            fmt = match.group(1)
+            rendered = formatter.render(cls, fmt)  # type: ignore[arg-type]
+
+            # Respect the indentation of the placeholder line.
+            line_start = doc.rfind("\n", 0, match.start())
+            if line_start == -1:
+                indent = ""
+            else:
+                indent_match = re.match(r"[ \t]*", doc[line_start + 1 : match.start()])
+                indent = indent_match.group() if indent_match else ""
+
+            if indent:
+                lines = rendered.split("\n")
+                rendered = lines[0] + "\n" + "\n".join(indent + line for line in lines[1:])
+
+            return rendered
+
+        cls.__doc__ = cls._STATECHART_RE.sub(_replace, doc)
 
     def __format__(cls, fmt: str) -> str:
         from .contrib.diagram.formatter import formatter

tests/machines/showcase_simple.py

@@ -3,6 +3,11 @@
 
 
 class SimpleSC(StateChart):
+    """A simple three-state machine.
+
+    {statechart:rst}
+    """
+
     idle = State(initial=True)
     running = State()
     done = State(final=True)

tests/test_contrib_diagram.py

@@ -1328,6 +1328,122 @@ def test_format_invalid_class_raises(self):
             f"{TrafficLightMachine:invalid}"
 
 
+class TestDocstringExpansion:
+    """Tests for {statechart:FORMAT} placeholder expansion in docstrings."""
+
+    def test_md_placeholder(self):
+        from statemachine.state import State
+        from statemachine.statemachine import StateChart
+
+        class MyMachine(StateChart):
+            """Machine.
+
+            {statechart:md}
+            """
+
+            s1 = State(initial=True)
+            s2 = State(final=True)
+
+            go = s1.to(s2)
+
+        assert "| State" in MyMachine.__doc__
+        assert "{statechart:md}" not in MyMachine.__doc__
+
+    def test_rst_placeholder(self):
+        from statemachine.state import State
+        from statemachine.statemachine import StateChart
+
+        class MyMachine(StateChart):
+            """Machine.
+
+            {statechart:rst}
+            """
+
+            s1 = State(initial=True)
+            s2 = State(final=True)
+
+            go = s1.to(s2)
+
+        assert "+---" in MyMachine.__doc__
+        assert "{statechart:rst}" not in MyMachine.__doc__
+
+    def test_mermaid_placeholder(self):
+        from statemachine.state import State
+        from statemachine.statemachine import StateChart
+
+        class MyMachine(StateChart):
+            """{statechart:mermaid}"""
+
+            s1 = State(initial=True)
+            s2 = State(final=True)
+
+            go = s1.to(s2)
+
+        assert "stateDiagram-v2" in MyMachine.__doc__
+
+    def test_no_placeholder_unchanged(self):
+        from statemachine.state import State
+        from statemachine.statemachine import StateChart
+
+        class MyMachine(StateChart):
+            """Just a plain docstring."""
+
+            s1 = State(initial=True)
+            s2 = State(final=True)
+
+            go = s1.to(s2)
+
+        assert MyMachine.__doc__ == "Just a plain docstring."
+
+    def test_no_docstring(self):
+        from statemachine.state import State
+        from statemachine.statemachine import StateChart
+
+        class MyMachine(StateChart):
+            s1 = State(initial=True)
+            s2 = State(final=True)
+
+            go = s1.to(s2)
+
+        assert MyMachine.__doc__ is None
+
+    def test_indentation_preserved(self):
+        from statemachine.state import State
+        from statemachine.statemachine import StateChart
+
+        class MyMachine(StateChart):
+            __doc__ = "Doc.\n\n    Table:\n\n    {statechart:md}\n\n    End.\n"
+
+            s1 = State(initial=True)
+            s2 = State(final=True)
+
+            go = s1.to(s2)
+
+        lines = MyMachine.__doc__.split("\n")
+        table_lines = [line for line in lines if "|" in line]
+        for line in table_lines:
+            assert line.startswith("    |")
+        assert "End." in MyMachine.__doc__
+
+    def test_multiple_placeholders(self):
+        from statemachine.state import State
+        from statemachine.statemachine import StateChart
+
+        class MyMachine(StateChart):
+            """MD: {statechart:md}
+
+            Mermaid: {statechart:mermaid}
+            """
+
+            s1 = State(initial=True)
+            s2 = State(final=True)
+
+            go = s1.to(s2)
+
+        assert "| State" in MyMachine.__doc__
+        assert "stateDiagram-v2" in MyMachine.__doc__
+
+
 class TestFormatter:
     """Tests for the Formatter facade (render, register_format, supported_formats)."""