docs: Improvements on the docs, removing jupyterlite (#331)

Author: fgmacedo

README.rst

@@ -1,6 +1,6 @@
-====================
-Python State Machine
-====================
+===================
+Python StateMachine
+===================
 
 
 .. image:: https://img.shields.io/pypi/v/python-statemachine.svg
@@ -112,7 +112,7 @@ Then start sending events:
 >>> traffic_light.cycle()
 'Running cycle from green to yellow'
 
-You can inspect about the current state:
+You can inspect the current state:
 
 >>> traffic_light.current_state.id
 'yellow'
@@ -151,13 +151,13 @@ Or over events:
 >>> [t.name for t in traffic_light.events]
 ['cycle', 'go', 'slowdown', 'stop']
 
-Call an event by it's name:
+Call an event by its name:
 
 >>> traffic_light.cycle()
 Don't move.
 'Running cycle from yellow to red'
 
-Or sending an event with the event name:
+Or send an event with the event name:
 
 >>> traffic_light.send('cycle')
 Go ahead!
@@ -180,8 +180,8 @@ True
 And you can pass arbitrary positional or keyword arguments to the event, and
 they will be propagated to all actions and callbacks:
 
->>> traffic_light.cycle(message="Please, now slowdon.")
-'Running cycle from green to yellow. Please, now slowdon.'
+>>> traffic_light.cycle(message="Please, now slowdown.")
+'Running cycle from green to yellow. Please, now slowdown.'
 
 
 Models

docs/actions.md

@@ -1,14 +1,14 @@
 # Actions
 
-An action is the way a StateMachine can cause things to happen in the
+Action is the way a StateMachine can cause things to happen in the
 outside world, and indeed they are the main reason why they exist at all.
 
 The main point of introducing a state machine is for the
 actions to be invoked at the right times, depending on the sequence of events
 and the state of the guards.
 
 Actions are most commonly performed on entry or exit of a state, although
-it is possible to add them before / after a transition.
+it is possible to add them before/after a transition.
 
 There are several action callbacks that you can define to interact with a
 StateMachine in execution.
@@ -257,9 +257,9 @@ You can also declare an event while also adding a callback:
 
 ```
 
-Note that with this syntax, the result `loop` that is present on the `ExampleStateMachine.loop`
+Note that with this syntax, the resulting `loop` that is present on the `ExampleStateMachine.loop`
 namespace is not a simple method, but an {ref}`event` trigger. So it only executes if the
-StateMachine is on the right state.
+StateMachine is in the right state.
 
 So, you can use the event-oriented approach:
 
@@ -275,8 +275,7 @@ On loop
 
 ## Other callbacks
 
-In addition to {ref}`actions`, you can specify {ref}`validators-and-guards` that are checked
-before an transition is started. They are meant to stop a transition to occur.
+In addition to {ref}`actions`, you can specify {ref}`validators and guards` that are checked before a transition is started. They are meant to stop a transition to occur.
 
 ```{seealso}
 See {ref}`guards` and {ref}`validators`.
@@ -320,7 +319,7 @@ Actions and Guards will be executed in the following order:
 
 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 expect to receive with the provided arguments.
+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
 the `source` ({ref}`state`), or the `event` ({ref}`event`), or access a keyword
@@ -346,10 +345,10 @@ 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 statemachine was when the {ref}`Event` started.
+: The {ref}`State` the state machine was when the {ref}`Event` started.
 
 `state`
-: The current {ref}`State` of the statemachine.
+: The current {ref}`State` of the state machine.
 
 `target`
 : The destination {ref}`State` of the transition.

docs/conf.py

@@ -50,7 +50,6 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.autosectionlabel",
     "sphinx_gallery.gen_gallery",
-    "jupyterlite_sphinx",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -243,11 +242,6 @@
     "event": "{ref}`event`",
 }
 
-# JupyterLite
-jupyterlite_config = "jupyterlite_config.json"
-jupyterlite_contents = ["./examples", "./auto_examples"]
-jupyterlite_dir = "./auto_examples"
-
 # Github
 
 html_context = {
@@ -271,10 +265,5 @@
     "min_reported_time": 9999,
     "thumbnail_size": (400, 280),
     "image_scrapers": (MachineScraper(project_root),),
-    "first_notebook_cell": (
-        "# import piplite\n"
-        "# await piplite.install('python-statemachine[diagrams]')\n"
-        "# import patch_repr_svg\n"
-    ),
     "reset_modules": [],
 }

docs/diagram.md

@@ -1,6 +1,6 @@
 # Diagrams
 
-You can generate diagrams from your statemachine.
+You can generate diagrams from your state machine.
 
 ```{note}
 This functionality depends on [pydot](https://github.com/pydot/pydot), it means that you need to
@@ -25,7 +25,7 @@ To install Graphviz, you can visit the [Graphviz website](https://graphviz.org/)
 instructions for your operating system. Alternatively, you can use a package manager to install
 Graphviz. For example, on Debian-based systems (such as Ubuntu), you can use the following command:
 
-    apt-get install graphviz
+    sudo apt install graphviz
 
 ```
 
@@ -81,6 +81,16 @@ The current state is also highlighted:
 ![OrderControl](images/order_control_machine_processing.png)
 
 
+```{hint}
+
+A handy shortcut to have the graph representation:
+
+```py
+>>> machine._graph()
+<pydot.Dot ...
+
+```
+
 ## Generate from the command line
 
 You can also generate a diagram from the command line using the `statemachine.contrib.diagram` as a module.
@@ -118,3 +128,13 @@ Machines instances are automatically displayed as a diagram when used on Jupyter
 
 
 ![Approval machine on JupyterLab](images/lab_approval_machine_accepted.png)
+
+
+## Don't want to install Graphviz
+
+
+```{eval-rst}
+.. autofunction:: statemachine.contrib.diagram.quickchart_write_svg
+```
+
+![OrderControl](images/oc_machine_processing.svg)