docs: Improved docs for 2.0 release (#352)

Author: fgmacedo

README.md

@@ -193,43 +193,6 @@ they will be propagated to all actions and callbacks:
 
 ```
 
-## Models
-
-If you need to persist the current state on another object, or you're using the
-state machine to control the flow of another object, you can pass this object
-to the `StateMachine` constructor:
-
-```py
->>> class MyModel(object):
-...     def __init__(self, state):
-...         self.state = state
-...
-
->>> obj = MyModel(state='red')
-
->>> traffic_light = TrafficLightMachine(obj)
-
->>> traffic_light.red.is_active
-True
-
->>> obj.state
-'red'
-
->>> obj.state = 'green'
-
->>> traffic_light.green.is_active
-True
-
->>> traffic_light.slowdown()
-
->>> obj.state
-'yellow'
-
->>> traffic_light.yellow.is_active
-True
-
-```
-
 ## A more useful example
 
 A simple didactic state machine for controlling an `Order`:

docs/index.md

@@ -11,6 +11,7 @@ states
 transitions
 actions
 guards
+models
 observers
 mixins
 integrations

docs/models.md

@@ -0,0 +1,28 @@
+
+# Domain models
+
+If you need to use any other object to persist the current state, or you're using the
+state machine to control the flow of another object, you can pass this object
+to the `StateMachine` constructor.
+
+If you don't pass an explicit model instance, this simple `Model` will be used:
+
+
+```{literalinclude} ../statemachine/model.py
+:language: python
+:linenos:
+```
+
+```{eval-rst}
+.. autoclass:: statemachine.model.Model
+    :members:
+```
+
+```{seealso}
+See the {ref}`sphx_glr_auto_examples_order_control_rich_model_machine.py` as example of using a domain object to hold attributes and methods to be used on the `StateMachine` definition.
+```
+
+```{hint}
+Domain models are registered as {ref}`observers`, so you can have the same level of functionalities provided to the built-in `StateMachine`, such as implementing all callbacks and guards on your domain model and keeping only the definition of states and transitions on
+the `StateMachine`.
+```

docs/observers.md

@@ -41,6 +41,11 @@ The `StateMachine` itself is registered as an observer, so by using `.add_observ
 external object can have the same level of functionalities provided to the built-in class.
 ```
 
+```{tip}
+{ref}`domain models` are also registered as an observer.
+```
+
+
 ```{seealso}
 See {ref}`actions`, {ref}`validators and guards` for a list of possible callbacks.
 

docs/releases/2.0.0.md

@@ -4,12 +4,11 @@
 
 Welcome to StateMachine 2.0.0!
 
-This version is the first to take advantage of the Python3 improvements. We're on our way to implementing features following the SCXML specs. We hope that you enjoy it.
+This version is the first to take advantage of the Python3 improvements and is a huge internal refactoring removing the deprecated features on 1.*. We hope that you enjoy it.
 
 These release notes cover the [](#whats-new-in-20), as well as
 some [backwards incompatible changes](#backwards-incompatible-changes-in-20) you'll
-want to be aware of when upgrading from StateMachine 1.*. We've
-[begun the deprecation process for some features](#deprecated-features-in-20).
+want to be aware of when upgrading from StateMachine 1.*.
 
 
 ## Python compatibility in 2.0
@@ -42,12 +41,12 @@ See {ref}`internal transition` for more details.
 
 ## Minor features in 2.0
 
-- Modernization of the development stack to use linters.
+- Modernization of the development tools to use linters and improved mypy support.
 - [#342](https://github.com/fgmacedo/python-statemachine/pull/342): Guards now supports the
-  evaluation of **truthy**** and **falsy** values.
+  evaluation of **truthy** and **falsy** values.
 - [#342](https://github.com/fgmacedo/python-statemachine/pull/342): Assignment of `Transition`
   guards using decorators is now possible.
-
+- [#331](https://github.com/fgmacedo/python-statemachine/pull/331): Added a way to generate diagrams using [QuickChart.io](https://quickchart.io) instead of GraphViz. See {ref}`diagrams` for more details.
 
 ## Bugfixes in 2.0
 
@@ -57,11 +56,91 @@ See {ref}`internal transition` for more details.
 
 ## Backward incompatible changes in 2.0
 
-- TODO
-### Other backward incompatible changes in 2.0
+- Dropped support for Django <= `1.6` for auto-discovering and registering `StateMachine` classes
+  to be used on {ref}`django integration`.
+
+### Statemachine class changes in 2.0
 
-- TODO
+#### `StateMachine.run` removed in favor of `StateMachine.send`
+
+```py
+from tests.examples.traffic_light_machine import TrafficLightMachine
+
+sm = TrafficLightMachine()
+sm.run("cycle")
+
+```
+
+Should become:
+
+```py
+>>> from tests.examples.traffic_light_machine import TrafficLightMachine
+
+>>> sm = TrafficLightMachine()
+>>> sm.send("cycle")
+'Running cycle from green to yellow'
+
+```
 
-## Deprecated features in 2.0
 
-- TODO
+#### `StateMachine.allowed_transitions` removed in favor of `StateMachine.allowed_events`
+
+```py
+from tests.examples.traffic_light_machine import TrafficLightMachine
+
+sm = TrafficLightMachine()
+assert [t.name for t in sm.allowed_transitions] == ["cycle"]
+
+```
+
+Should become:
+
+```py
+>>> from tests.examples.traffic_light_machine import TrafficLightMachine
+
+>>> sm = TrafficLightMachine()
+>>> assert [t.name for t in sm.allowed_events] == ["cycle"]
+
+```
+
+#### `Statemachine.is_<state>` removed in favor of `StateMachine.<state>.is_active`
+
+```py
+from tests.examples.traffic_light_machine import TrafficLightMachine
+
+sm = TrafficLightMachine()
+assert sm.is_green
+
+```
+
+Should become:
+
+```py
+>>> from tests.examples.traffic_light_machine import TrafficLightMachine
+
+>>> sm = TrafficLightMachine()
+>>> assert sm.green.is_active
+
+```
+
+### State class changes in 2.0
+
+#### `State.identification` removed in favor of `State.id`
+
+```py
+from tests.examples.traffic_light_machine import TrafficLightMachine
+
+sm = TrafficLightMachine()
+assert sm.current_state.identification == "green"
+
+```
+
+Should become:
+
+```py
+>>> from tests.examples.traffic_light_machine import TrafficLightMachine
+
+>>> sm = TrafficLightMachine()
+>>> assert sm.current_state.id == "green"
+
+```

docs/releases/index.md

@@ -34,7 +34,7 @@ This is the last release series to support Python 2.X series.
 
 ```
 
-###  0.* releases
+###  0.* release
 
 ```{toctree}
 :maxdepth: 1