docs: merge mixins.md into integrations.md and move API ref to api.md

Remove the standalone mixins.md page (not in toctree). Move the
MachineMixin autoclass reference to api.md alongside other API docs,
and consolidate the usage examples into integrations.md with a
cleaner narrative flow.

Author: fgmacedo

docs/api.md

@@ -126,6 +126,18 @@ class MyMachine(StateChart):
         ...
 ```
 
+## MachineMixin
+
+```{seealso}
+{ref}`Integrations <machinemixin>` for usage examples.
+```
+
+```{eval-rst}
+.. autoclass:: statemachine.mixins.MachineMixin
+    :members:
+    :undoc-members:
+```
+
 ## create_machine_class_from_definition
 
 ```{versionadded} 3.0.0

docs/integrations.md

@@ -1,44 +1,125 @@
 
 # Integrations
 
-(django integration)=
 (machinemixin)=
+## MachineMixin
+
+{ref}`Domain models` can inherit from `MachineMixin` to automatically instantiate
+and bind a {ref}`StateChart` to any Python class. This is the foundation for
+integrating state machines with ORMs and other domain objects.
+
+```{seealso}
+See the [MachineMixin API reference](api.md#machinemixin) for the full list of attributes.
+```
+
+### Example
+
+Given this state machine:
+
+```py
+>>> from statemachine import StateChart, State
+
+>>> from statemachine.mixins import MachineMixin
+
+>>> class CampaignMachine(StateChart):
+...     "A workflow machine"
+...     draft = State('Draft', initial=True, value=1)
+...     producing = State('Being produced', value=2)
+...     closed = State('Closed', value=3, final=True)
+...     cancelled = State('Cancelled', value=4, final=True)
+...
+...     add_job = draft.to.itself() | producing.to.itself()
+...     produce = draft.to(producing)
+...     deliver = producing.to(closed)
+...     cancel = cancelled.from_(draft, producing)
+
+```
+
+You can attach it to a model by inheriting from `MachineMixin` and setting
+`state_machine_name` to the fully qualified class name:
+
+``` py
+>>> class Workflow(MachineMixin):
+...     state_machine_name = '__main__.CampaignMachine'
+...     state_machine_attr = 'sm'
+...     state_field_name = 'workflow_step'
+...     bind_events_as_methods = True
+...
+...     workflow_step = 1
+
+```
+
+When a `Workflow` instance is created, it automatically receives a `CampaignMachine`
+instance at the `state_machine_attr` attribute. The state value is read from and
+written to the `state_field_name` field:
+
+``` py
+>>> model = Workflow()
+
+>>> isinstance(model.sm, CampaignMachine)
+True
+
+>>> model.workflow_step
+1
+
+>>> model.sm.draft in model.sm.configuration
+True
+
+```
+
+With `bind_events_as_methods = True`, events become methods on the model itself:
+
+``` py
+>>> model.produce()
+>>> model.workflow_step
+2
+
+>>> model.sm.cancel()  # you can still call the SM directly
+
+>>> model.workflow_step
+4
+
+>>> model.sm.cancelled in model.sm.configuration
+True
+
+```
+
+```{note}
+In this example `state_machine_name` uses a `__main__` prefix because the class
+is defined inline for doctest purposes. In your code, use the fully qualified
+path (e.g., `'myapp.statemachines.CampaignMachine'`).
+```
+
+(django integration)=
 ## Django integration
 
 When used in a Django App, this library implements an auto-discovery hook similar to how Django's
 built-in **admin** [autodiscover](https://docs.djangoproject.com/en/dev/ref/contrib/admin/#django.contrib.admin.autodiscover).
 
-> This library attempts to import an **statemachine** or **statemachines** module in each installed
+> This library attempts to import a **statemachine** or **statemachines** module in each installed
 > application. Such modules are expected to register `StateChart` classes to be used with
 > the {ref}`MachineMixin`.
 
 
 ```{hint}
-When using `python-statemachine` to control the state of a Django model, we advise keeping the
-{ref}`StateChart` definitions on their own modules.
+We advise keeping {ref}`StateChart` definitions in their own modules to avoid circular
+references. If you place state machines in modules named `statemachine` or `statemachines`
+inside installed Django Apps, they will be automatically imported and registered.
 
-So as circular references may occur, and as a way to help you organize your
-code, if you put state machines on modules named as mentioned above inside installed
-Django Apps, these {ref}`StateChart` classes will be automatically
-imported and registered.
-
-This is only an advice, nothing stops you do declare your state machine alongside your models.
+That said, nothing stops you from declaring your state machine alongside your models.
 ```
 
 
-### Example
-
-Given this StateMachine:
+### Django example
 
 ```py
 # campaign/statemachines.py
 
 from statemachine import StateChart
 from statemachine import State
-from statemachine.mixins import MachineMixin
 
 
-class CampaignMachineWithKeys(StateChart):
+class CampaignMachine(StateChart):
     "A workflow machine"
     draft = State('Draft', initial=True, value=1)
     producing = State('Being produced', value=2)
@@ -51,27 +132,25 @@ class CampaignMachineWithKeys(StateChart):
     cancel = cancelled.from_(draft, producing)
 ```
 
-Integrate with your model:
+Integrate with your Django model using `MachineMixin`:
 
 ```py
 # campaign/models.py
 
 from django.db import models
 
+from statemachine.mixins import MachineMixin
+
+
 class Campaign(models.Model, MachineMixin):
-    state_machine_name = 'campaign.statemachines.CampaignMachineWithKeys'
+    state_machine_name = 'campaign.statemachines.CampaignMachine'
     state_machine_attr = 'sm'
     state_field_name = 'step'
 
     name = models.CharField(max_length=30)
     step = models.IntegerField()
 ```
 
-
-```{seealso}
-Learn more about using the [](mixins.md#machinemixin).
-```
-
 ### Data migrations
 
 Django's `apps.get_model()` returns **historical model** classes that are dynamically created