chore: Docs improvements; removing mermaid from docs build

Author: fgmacedo

docs/conf.py

@@ -48,7 +48,6 @@
     "sphinx.ext.doctest",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
-    "sphinxcontrib.mermaid",
     "sphinx.ext.autosectionlabel",
     "sphinx_gallery.gen_gallery",
     "jupyterlite_sphinx",

docs/requirements.txt

@@ -3,7 +3,6 @@ Sphinx<5.0.0
 sphinx_rtd_theme==1.1.1
 sphinx-markdown-builder==0.5.5
 myst-parser==0.18.1
-sphinxcontrib-mermaid==0.7.1
 jupyterlite-sphinx==0.7.2
 sphinx-gallery==0.11.1
 matplotlib==3.6.2

docs/transitions.md

@@ -64,17 +64,8 @@ TransitionList([Transition(State('Draft', ...
 
 Consider this traffic light machine as example:
 
-```{mermaid}
-:align: center
+![TrafficLightMachine](images/traffic_light_machine.png)
 
-stateDiagram-v2
-direction LR
-[*] --> green
-green --> yellow: cycle
-yellow --> red: cycle
-red --> green: cycle
-
-```
 
 There're tree transitions, one starting from green to yellow, another from
 yellow to red, and another from red back to green. All these transitions

statemachine/statemachine.py

@@ -150,7 +150,7 @@ def allowed_transitions(self):
 
     @property
     def allowed_events(self):
-        "get the callable proxy of the current allowed transitions"
+        "get the callable proxy of the current allowed events"
         return [
             getattr(self, event)
             for event in self.current_state.transitions.unique_events

statemachine/transition.py

@@ -7,17 +7,26 @@
 
 
 class Transition(object):
-    """
-    A transition holds reference to the source and target state.
+    """A transition holds reference to the source and target state.
 
     Args:
-        source (State): The origin :ref:`State` of the transition.
-        target (State): The target :ref:`State` of the transition.
+        source (State): The origin state of the transition.
+        target (State): The target state of the transition.
         event (Optional[Union[str, List[str]]]): List of designators of events that trigger this
-            transition.
-
-            Can be either a list of strings, or a space-separated string list of event
+            transition. Can be either a list of strings, or a space-separated string list of event
             descriptors.
+        validators (Optional[Union[str, Callable, List[Callable]]]): The validation callbacks to
+            be invoked before the transition is executed.
+        cond (Optional[Union[str, Callable, List[Callable]]]): The condition callbacks to be
+            invoked before the transition is executed that should evaluate to `True`.
+        unless (Optional[Union[str, Callable, List[Callable]]]): The condition callbacks to be
+            invoked if the `cond` is False before the transition is executed.
+        on (Optional[Union[str, Callable, List[Callable]]]): The callbacks to be invoked
+            when the transition is executed.
+        before (Optional[Union[str, Callable, List[Callable]]]): The callbacks to be invoked
+            before the transition is executed.
+        after (Optional[Union[str, Callable, List[Callable]]]): The callbacks to be invoked
+            after the transition is executed.
     """
 
     def __init__(