feat: add statemachine-diagram Sphinx directive for inline diagram rendering

Add a Sphinx extension that renders state machine diagrams inline in docs
from an importable class path, eliminating manual DotGraphMachine/write_png
boilerplate. Supports standard image/figure options (width, height, scale,
align, target, class, name) and state-machine-specific options (events,
caption, figclass).

Key features:
- Inline SVG rendering (no intermediate files)
- :events: option to instantiate and advance the machine before rendering
- :target: (empty) auto-generates a standalone SVG for full-size zoom
- Responsive sizing: intrinsic width becomes max-width, scales down on
  narrow viewports
- Compatible with any Sphinx theme (uses native align-center/left/right
  classes)

Refactor diagram.md to use the directive for the visual showcase, replacing
doctest+write_png workflow. Extract showcase machines to tests/machines/
and use literalinclude with :pyobject: to display source code. Reorganize
the page narrative: _graph() as primary entry point, DotGraphMachine for
advanced customization.

Author: fgmacedo

docs/conf.py

@@ -51,6 +51,7 @@
     "sphinx.ext.autosectionlabel",
     "sphinx_gallery.gen_gallery",
     "sphinx_copybutton",
+    "statemachine.contrib.diagram.sphinx_ext",
 ]
 
 autosectionlabel_prefix_document = True