Add docs for LaunchMode and StartMode

docs/transitions/index.rst

@@ -105,3 +105,21 @@ To close a dialog you have to methods:
 Parent dialog has no access to the context of child one. But you can pass some data as a result to ``done()`` method and then process it in ``on_process_result`` callback of parent dialog.
 
 .. literalinclude:: ./done.py
+
+LaunchMode
+=================
+
+**LaunchMode** is a mode for launching new dialogs. It helps manage the dialog stack and ensures dialogs are handled appropriately based on their type.
+
+.. literalinclude:: ./launchmode.py
+
+.. autoclass:: aiogram_dialog.api.entities.launch_mode.LaunchMode(Enum)
+
+StartMode
+=================
+
+**StartMode** is a mode for starting new dialog. It defines how the current stack should be handled when initiating a new dialog.
+
+.. literalinclude:: ./startmode.py
+
+.. autoclass:: aiogram_dialog.api.entities.modes.StartMode(Enum)

docs/transitions/launchmode.py

@@ -0,0 +1,4 @@
+dialog = Dialog(
+    Window(...),
+    launch_mode=LaunchMode.SINGLE_TOP,
+)

docs/transitions/startmode.py

@@ -0,0 +1,2 @@
+async def start(message: Message, dialog_manager: DialogManager):
+    await dialog_manager.start(..., mode=StartMode.RESET_STACK)

src/aiogram_dialog/api/entities/launch_mode.py

@@ -3,22 +3,33 @@
 
 class LaunchMode(Enum):
     """
+
     Modes of launching new dialog.
 
-    `ROOT` dialogs will be always a root dialog in stack.
+    **ROOT**:
+        dialogs will be always a root dialog in stack.
+
         Starting such dialogs will automatically reset stack.
+
         Example: main menu
 
-    `EXCLUSIVE` dialogs can be only a single dialog in stack.
+    **EXCLUSIVE**:
+        dialogs can be only a single dialog in stack.
+
         Starting such dialogs will automatically reset stack.
         Starting other dialogs on top of them is forbidden
-        Example: Banners
 
-    `SINGLE_TOP` dialogs will not be repeated on top of stack.
+        Example: banners
+
+    **SINGLE_TOP**:
+        dialogs will not be repeated on top of stack.
+
         Starting the same dialog right on top of it will just replace it.
+
         Example: product page
 
-    `STANDARD` dialogs have no limitations themselves
+    **STANDARD**:
+        dialogs have no limitations themselves
     """
 
     STANDARD = "standard"

src/aiogram_dialog/api/entities/modes.py

@@ -5,25 +5,25 @@ class ShowMode(Enum):
     """
     Modes of show dialog message when new update handled.
 
-    AUTO:
+    **AUTO**:
         default show mode.
 
         Uses `SEND mode` when new message from user handled or `EDIT mode`
         when any other updated handled.
 
-    EDIT:
+    **EDIT**:
         edit dialog message
 
-    SEND:
+    **SEND****:
         send new dialog message
 
-    DELETE_AND_SEND:
+    **DELETE_AND_SEND**:
         delete and send new dialog message
 
         `Attention`: Telegram's restrictions will prevent the deletion of the
         message when more than 2 days has elapsed.
 
-    NO_UPDATE:
+    **NO_UPDATE**:
         will not update and rerender the dialog message
     """
 
@@ -35,6 +35,30 @@ class ShowMode(Enum):
 
 
 class StartMode(Enum):
+    """
+    Modes of starting a new dialog.
+
+    **NORMAL**:
+        default start mode.
+
+        This mode continues from the current state without resetting or
+        creating a new stack.
+
+    **RESET_STACK**:
+        reset the current stack.
+
+        This mode clears the existing stack and starts fresh. It is used when
+        the existing stack needs to be discarded and a new operation stack
+        is required.
+
+    **NEW_STACK**:
+        start with a new stack.
+
+        This mode initiates a new stack while retaining the old one, useful
+        when a new sequence of operations is to be started alongside the
+        current one.
+    """
+
     NORMAL = "NORMAL"
     RESET_STACK = "RESET_STACK"
     NEW_STACK = "NEW_STACK"