Migration guide 2.x -> 3.0 (#1143)

* Initial commit for docs cleanup

* Update migration guide

* More docs

* Added changes description

* Small fixes

docs/dispatcher/errors.rst

@@ -0,0 +1,49 @@
+######
+Errors
+######
+
+
+Handling errors
+===============
+
+Is recommended way that you should use errors inside handlers using try-except block,
+but in common cases you can use global errors handler at router or dispatcher level.
+
+If you specify errors handler for router - it will be used for all handlers inside this router.
+
+If you specify errors handler for dispatcher - it will be used for all handlers inside all routers.
+
+.. code-block:: python
+
+    @router.error(ExceptionTypeFilter(MyCustomException), F.update.message.as_("message"))
+    async def handle_my_custom_exception(event: ErrorEvent, message: Message):
+        # do something with error
+        await message.answer("Oops, something went wrong!")
+
+
+    @router.error()
+    async def error_handler(event: ErrorEvent):
+        logger.critical("Critical error caused by %s", event.exception, exc_info=True)
+        # do something with error
+        ...
+
+
+.. _error-event:
+
+ErrorEvent
+==========
+
+.. automodule:: aiogram.types.error_event
+    :members:
+    :member-order: bysource
+    :undoc-members: True
+    :exclude-members: model_config,model_fields
+
+.. _error-types:
+
+Error types
+===========
+
+.. automodule:: aiogram.exceptions
+    :members:
+    :member-order: bysource

docs/dispatcher/filters/callback_data.rst

@@ -1,3 +1,5 @@
+.. _callback-data-factory
+
 ==============================
 Callback Data Factory & Filter
 ==============================

docs/dispatcher/index.rst

@@ -17,7 +17,6 @@ Dispatcher is subclass of router and should be always is root router.
 
 .. toctree::
 
-    observer
     router
     dispatcher
     class_based_handlers/index
@@ -25,3 +24,4 @@ Dispatcher is subclass of router and should be always is root router.
     middlewares
     finite_state_machine/index
     flags
+    errors

docs/dispatcher/middlewares.rst

@@ -1,3 +1,5 @@
+.. _middlewares:
+
 ===========
 Middlewares
 ===========

docs/dispatcher/observer.rst

@@ -1,26 +0,0 @@
-########
-Observer
-########
-
-Observer is used for filtering and handling different events. That is part of internal API with some public methods and is recommended to don't use methods is not listed here.
-
-In `aiogram` framework is available two variants of observer:
-
-- `EventObserver <#eventobserver>`__
-- `TelegramEventObserver <#telegrameventobserver>`__
-
-
-EventObserver
-=============
-
-.. autoclass:: aiogram.dispatcher.event.event.EventObserver
-    :members: register, trigger, __call__
-    :member-order: bysource
-
-
-TelegramEventObserver
-=====================
-
-.. autoclass:: aiogram.dispatcher.event.telegram.TelegramEventObserver
-    :members: register, trigger, __call__, bind_filter, middleware, outer_middleware
-    :member-order: bysource

docs/dispatcher/router.rst

@@ -3,10 +3,12 @@ Router
 ######
 
 .. autoclass:: aiogram.dispatcher.router.Router
-    :members: __init__, include_router
+    :members: __init__, include_router, include_routers, resolve_used_update_types
     :show-inheritance:
 
 
+.. _Event observers:
+
 Event observers
 ===============
 
@@ -19,19 +21,6 @@ Here is the list of available observers and examples of how to register handlers
 
 In these examples only decorator-style registering handlers are used, but if you don't like @decorators just use :obj:`<event type>.register(...)` method instead.
 
-Update
-------
-
-.. code-block:: python
-
-    @router.update()
-    async def message_handler(update: types.Update) -> Any: pass
-
-.. note::
-
-    By default Router already has an update handler which route all event types to another observers.
-
-
 Message
 -------
 
@@ -143,9 +132,12 @@ Errors
     @router.errors()
     async def error_handler(exception: ErrorEvent) -> Any: pass
 
-Is useful for handling errors from other handlers
+Is useful for handling errors from other handlers, error event described :ref:`here <error-event>`
 
 
+
+.. _Nested routers:
+
 Nested routers
 ==============
 
@@ -159,8 +151,8 @@ Nested routers
 Example:
 
 .. code-block:: python
-    :caption: module_2.py
-    :name: module_2
+    :caption: module_1.py
+    :name: module_1
 
     router2 = Router()
 
@@ -170,7 +162,7 @@ Example:
 
 .. code-block:: python
     :caption: module_2.py
-    :name: module_1
+    :name: module_2
 
     from module_2 import router2
 
@@ -179,6 +171,22 @@ Example:
     router1.include_router(router2)
 
 
+Update
+------
+
+.. code-block:: python
+
+    @dispatcher.update()
+    async def message_handler(update: types.Update) -> Any: pass
+
+.. warning::
+
+    The only root Router (Dispatcher) can handle this type of event.
+
+.. note::
+
+    Dispatcher already has default handler for this event type, so you can use it for handling all updates that are not handled by any other handlers.
+
 How it works?
 -------------