Extended the documentation to show a few more (#340)

* Extended the documentation to show a few more
usage examples
* Documentation: Update transition documentation
* Corrected the description of how to add transitions
using multiple lines

Author: Rosi2143

docs/actions.md

@@ -87,9 +87,9 @@ All actions and {ref}`guards` support multiple method signatures. They follow th
 
 For each defined {ref}`state`, you can declare `enter` and `exit` callbacks.
 
-### Declare state actions by name convention
+### Declare state actions by naming convention
 
-Callbacks by name convention will be searched on the StateMachine and on the
+Callbacks by naming convention will be searched on the StateMachine and on the
 model, using the patterns:
 
 - `on_enter_<state.id>()`
@@ -158,11 +158,11 @@ Use the `enter` or `exit` params available on the `State` constructor.
 
 For each {ref}`event`, you can register `before`, `on` and `after` callbacks.
 
-### Declare transition actions by name convention
+### Declare transition actions by naming convention
 
 The action will be registered for every {ref}`transition` associated with the event.
 
-Callbacks by name convention will be searched on the StateMachine and on the
+Callbacks by naming convention will be searched on the StateMachine and on the
 model, using the patterns:
 
 - `before_<event>()`
@@ -325,8 +325,8 @@ Actions and Guards will be executed in the following order:
 (dynamic-dispatch)=
 ## Dynamic dispatch
 
-python-statemachine implements a custom dispatch mechanism on all those available Actions and
-Guards, this means that you can declare an arbitrary number of `*args` and `**kwargs`, and the
+`python-statemachine` implements a custom dispatch mechanism on all those available Actions and
+Guards. This means that you can declare an arbitrary number of `*args` and `**kwargs`, and the
 library will match your method signature of what's expected to receive with the provided arguments.
 
 This means that if on your `on_enter_<state.id>()` or `on_execute_<event>()` method, you need to know
@@ -353,7 +353,7 @@ For your convenience, all these parameters are available for you on any Action o
 : The {ref}`Event` that was triggered.
 
 `source`
-: The {ref}`State` the state machine was when the {ref}`Event` started.
+: The {ref}`State` the state machine was in when the {ref}`Event` started.
 
 `state`
 : The current {ref}`State` of the state machine.

docs/guards.md

@@ -5,7 +5,7 @@ Validations and Guards are checked before an transition is started. They are mea
 transition to occur.
 
 The main difference, is that {ref}`validators` raise exceptions to stop the flow, and {ref}`guards`
-act like predicates that should resolve for a ``boolean`` value.
+act like predicates that shall resolve to a ``boolean`` value.
 
 ```{seealso}
 Please see {ref}`dynamic-dispatch` to know more about how this lib supports multiple signatures
@@ -18,13 +18,12 @@ Also known as **Conditional transition**.
 
 A guard is a condition that may be checked when a statemachine wants to handle
 an {ref}`event`. A guard is declared on the {ref}`transition`, and when that transition
-would trigger, then the guard (if any) is checked.  If the guard is `True`
+would trigger, then the guard (if any) is checked. If the guard is `True`
 then the transition does happen. If the guard is `False`, the transition
 is ignored.
 
 When transitions have guards, then it's possible to define two or more
-transitions for the same event from the same {ref}`state`, i.e. that a state has
-two (or more) transitions for the same event.  When the event happens, then
+transitions for the same event from the same {ref}`state`. When the event happens, then
 the guarded transitions are checked, one by one, and the first transition
 whose guard is true will be used, the others will be ignored.
 
@@ -37,9 +36,13 @@ There are two variations of Guard clauses available:
 cond
 : A list of conditions, acting like predicates. A transition is only allowed to occur if
 all conditions evaluate to ``True``.
+* Single condition: `cond="condition"`
+* Multiple conditions: `cond=["condition1", "condition2"]`
 
 unless
-: Same as `cond`, but the transition is allowed if all conditions evaluate to `False`.
+: Same as `cond`, but the transition is only allowed if all conditions evaluate to ``False``.
+* Single condition: `unless="condition"`
+* Multiple conditions: `unless=["condition1", "condition2"]`
 
 ```{hint}
 In Python, a boolean value is either `True` or `False`. However, there are also specific values that
@@ -48,9 +51,9 @@ are considered "**falsy**" and will evaluate as `False` when used in a boolean c
 These include:
 
 1. The special value `None`.
-1. Numeric values of `0` or `0.0`.
-1. **Empty** strings, lists, tuples, sets, and dictionaries.
-1. Instances of certain classes that define a `__bool__()` or `__len__()` method that returns
+2. Numeric values of `0` or `0.0`.
+3. **Empty** strings, lists, tuples, sets, and dictionaries.
+4. Instances of certain classes that define a `__bool__()` or `__len__()` method that returns
    `False` or `0`, respectively.
 
 On the other hand, any value that is not considered "**falsy**" is considered "**truthy**" and will evaluate to `True` when used in a boolean context.
@@ -64,8 +67,14 @@ So, a condition `s1.to(s2, cond=lambda: [])` will evaluate as `False`, as an emp
 
 Are like {ref}`guards`, but instead of evaluating to boolean, they are expected to raise an
 exception to stop the flow. It may be useful for imperative style programming when you don't
-wanna to continue evaluating other possible transitions and exit immediately.
+want to continue evaluating other possible transitions and exit immediately.
 
+* Single validator: `validators="validator"`
+* Multiple validator: `validators=["validator1", "validator2"]`
+
+Both conditions and validators can also be combined for a single event.
+
+    <event> = <state1>.to(<state2>, cond="condition1", unless="condition2", validators="validator")
 
 Consider this example:
 
@@ -76,16 +85,23 @@ class InvoiceStateMachine(StateMachine):
     paid = State("paid")
     failed = State("failed")
 
+    paused = False
+    offer_valid = True
+
     pay = (
-        unpaid.to(paid, cond="payment_success")
-        | failed.to(paid)
-        | unpaid.to(failed)
+        unpaid.to(paid, cond="payment_success") |
+        unpaid.to(failed, validators="validator", unless="paused") |
+        failed.to(paid, cond=["payment_success", "offer_valid"])
     )
-
     def payment_success(self, event_data):
-        return <validation logic goes here>
+        return <condition logic goes here>
 
+    def validator(self):
+        return <validator logic goes here>
+```
+```{seealso}
+See the example {ref}`sphx_glr_auto_examples_all_actions_machine.py` for a complete example of
+validators and guards.
 ```
-
 
 Reference: [Statecharts](https://statecharts.dev/).

docs/images/order_control_machine_initial.png

@@ -2,5 +2,5 @@
 
 *January 11, 2023*
 
-This release tag was replaced by [](1.0.1.md) due to an error on the metadata when uploading to
+This release tag was replaced by [1.0.1](1.0.1.md) due to an error on the metadata when uploading to
 pypi.

docs/images/order_control_machine_processing.png

@@ -6,7 +6,7 @@ Welcome to StateMachine 1.0.1!
 
 This version is a huge refactoring adding a lot of new and exciting features. We hope that you enjoy it.
 
-These release notes cover the [](#whats-new-in-10), as well as
+These release notes cover the [new features in 1.0](#whats-new-in-10), as well as
 some [backwards incompatible changes](#backwards-incompatible-changes-in-10) you'll
 want to be aware of when upgrading from StateMachine 0.9.0 or earlier. We've
 [begun the deprecation process for some features](#deprecated-features-in-10).

docs/images/test_state_machine_internal.png

@@ -52,6 +52,9 @@ In an executing state machine, a transition is a transfer from one state to anot
 A transition can define {ref}`actions` that will be executed whenever that transition
 is executed.
 
+Transitions can be filtered with {ref}`guards` allowing you to add conditions when a
+transition may be executed.
+
 An action associated with an event (before, on, after), will be assigned to all transitions
 bounded that uses the event as trigger.
 ```
@@ -63,7 +66,7 @@ bounded that uses the event as trigger.
 
 ```{hint}
 Usually you don't need to import and use a {ref}`transition` class directly in your code,
-one of the most powerful features of this library is now transitions and events can be expressed
+one of the most powerful features of this library is how transitions and events can be expressed
 linking directly from/to {ref}`state` instances.
 ```
 
@@ -150,7 +153,7 @@ Usage:
 
 ```{note}
 
-The internal transition is represented like an entry/exit action, where
+The internal transition is represented the same way as an entry/exit action, where
 the event name is used to describe the transition.
 
 ```
@@ -159,7 +162,7 @@ the event name is used to describe the transition.
 ## Event
 
 An event is an external signal that something has happened.
-They are sent to a state machine and allow the state machine to react.
+They are send to a state machine and allow the state machine to react.
 
 An event starts a {ref}`transition`, which can be thought of as a "cause" that
 initiates a change in the state of the system.
@@ -171,12 +174,16 @@ In `python-statemachine`, an event is specified as an attribute of the state mac
 Triggering an event on a state machine means invoking or sending a signal, initiating the
 process that may result in executing a transition.
 
-This process usually involves checking the current state, evaluating any guard conditions
-associated with the transition, executing any actions associated with the transition and states,
-and finally updating the current state.
+This process usually involves
+
+1. checking the current state
+1. evaluating any guard conditions
+associated with the transition
+1. executing any actions associated with the transition and (current and target) states
+1. finally updating the current state.
 
 ```{seealso}
-See {ref}`actions` and {ref}`validator sand guards`.
+See {ref}`actions` and {ref}`validators and guards`.
 ```
 
 

docs/releases/1.0.0.md

@@ -47,14 +47,22 @@ class State:
     >>> draft.to(producing)
     TransitionList([Transition(State('Draft', ...
 
-    The result is a `TransitionList`. Don't worry about this internal class. But the good
-    thing is that it implements the ``OR`` operator to combine transitions, so you can use the
-    ``|`` syntax to compound a list of transitions and assign to the same event.
+    The result is a `TransitionList`.
+    Don't worry about this internal class.
+    But the good thing is that it implements the ``OR`` operator to combine transitions,
+    so you can use the ``|`` syntax to compound a list of transitions and assign
+    to the same event.
 
-    >>> transitions = draft.to(draft) | draft.to(producing)
+    You can declare all transitions for a state in one single line ...
+
+    >>> transitions = draft.to(draft) | producing.to(closed)
+
+    ... and you can append additional transitions for a state to previous definitions.
+
+    >>> transitions |= closed.to(draft)
 
     >>> [(t.source.name, t.target.name) for t in transitions]
-    [('Draft', 'Draft'), ('Draft', 'Producing')]
+    [('Draft', 'Draft'), ('Producing', 'Closed'), ('Closed', 'Draft')]
 
     There are handy shortcuts that you can use to express this same set of transitions.