feat: Mermaid diagrams, transition tables, and format() support

[fgmacedo]

Summary

• Mermaid renderer — new MermaidRenderer produces stateDiagram-v2 source from the diagram IR, with a workaround for mermaid-js/mermaid#4052 (compound states inside parallel regions). Cross-boundary transitions (e.g., targeting a history pseudo-state inside a compound) are correctly rendered at the parent scope.

• Transition table renderer — TransitionTableRenderer produces Markdown or reStructuredText tables from the diagram IR.

• Formatter facade — decorator-based format registry with built-in formats: mermaid, md/markdown, rst, dot, svg. Powers both format(sm, "mermaid") / f"{sm:mermaid}" and the CLI.

• StateChart.__format__ — delegates to Formatter, enabling f-string and format() usage.

• Docstring auto-expansion — {statechart:FORMAT} placeholders in class docstrings are replaced at class creation time (via the metaclass) with the rendered diagram text.

• Sphinx directive — :format: mermaid option on statemachine-diagram emits a Mermaid node (via sphinxcontrib-mermaid).

• CLI enhancements — --format mermaid|md|rst and stdout output (-).

• Visual showcase — every showcase section in docs/diagram.md now includes both Graphviz and Mermaid renderings side by side, plus a new "Parallel with cross-boundary transitions" section.

• Documentation — revised diagram.md, tutorial, and 3.1.0 release notes.

Examples

f-string / format()

from tests.machines.showcase_simple import SimpleSC

sm = SimpleSC()

print(f"{sm:mermaid}")
# stateDiagram-v2
#     direction LR
#     state "Idle" as idle
#     state "Running" as running
#     state "Done" as done
#     [*] --> idle
#     done --> [*]
#     idle --> running : start
#     running --> done : finish
#
#     classDef active fill:#40E0D0,stroke:#333
#     idle:::active

print(format(SimpleSC, "md"))
# | State   | Event  | Guard | Target  |
# | ------- | ------ | ----- | ------- |
# | Idle    | start  |       | Running |
# | Running | finish |       | Done    |

Docstring auto-expansion

class SimpleSC(StateChart):
    """A simple three-state machine.

    {statechart:rst}
    """
    idle = State(initial=True)
    running = State()
    done = State(final=True)

    start = idle.to(running)
    finish = running.to(done)

At class creation time, {statechart:rst} is replaced with the rendered table:

>>> print(SimpleSC.__doc__)
A simple three-state machine.

+---------+--------+-------+---------+
| State   | Event  | Guard | Target  |
+=========+========+=======+=========+
| Idle    | start  |       | Running |
+---------+--------+-------+---------+
| Running | finish |       | Done    |
+---------+--------+-------+---------+

Mermaid workaround for parallel regions

Transitions targeting a compound state inside a parallel region crash Mermaid (mermaid-js/mermaid#4052). The renderer redirects them to the compound's initial child:

class ParallelCompoundSC(StateChart):
    class pipeline(State.Parallel, name="Pipeline"):
        class build(State.Compound, name="Build"):
            compile = State(initial=True)
            link = State(final=True)
            do_build = compile.to(link)

        class test(State.Compound, name="Test"):
            unit = State(initial=True)
            e2e = State(final=True)
            do_test = unit.to(e2e)

    idle = State(initial=True)
    review = State()

    start = idle.to(pipeline)
    done_state_pipeline = pipeline.to(review)
    rebuild = review.to(pipeline.build)   # targets compound inside parallel!
    accept = review.to(idle)

In the Mermaid output, rebuild is redirected from the compound to its initial child:

review --> compile : rebuild   # redirected: build -> compile (initial child)

Graphviz renders the arrow to the Build compound border; Mermaid redirects it to Compile.

CLI

# Mermaid to stdout
python -m statemachine.contrib.diagram myapp.MyMachine - --format mermaid

# Markdown table to file
python -m statemachine.contrib.diagram myapp.MyMachine table.md --format md

Sphinx directive

.. statemachine-diagram:: myapp.MyMachine
   :format: mermaid
   :caption: State diagram (Mermaid)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (19556ce) to head (fc082f2).
⚠️ Report is 1 commits behind head on develop.

Additional details and impacted files

@@            Coverage Diff             @@
##           develop      #595    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files           39        42     +3     
  Lines         4597      5007   +410     
  Branches       734       813    +79     
==========================================
+ Hits          4597      5007   +410     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.8% Duplication on New Code

See analysis details on SonarQube Cloud