Add base documentation of Dispatcher (not ready, not fully documented)

docs/dispatcher/dispatcher.md

@@ -0,0 +1,64 @@
+# Dispatcher
+Imports:
+
+- Recommended: `#!python3 from aiogram import Dispatcher`
+- Real location: `#!python3 from aiogram.dispatcher.dispatcher import Dispatcher`
+
+In code Dispatcher can be used directly for routing updates or attach another routers into dispatcher.
+
+!!! warning
+
+    Dispatcher is root [Router](router.md) and can not be included into another routers.
+
+
+Here is only listed base information about Dispatcher. All about writing handlers, filters and etc. you can found in next pages:
+
+- [Router](router.md).
+- [Observer](observer.md).
+
+## Simple usage
+Example:
+```python3
+dp = Dispatcher()
+
+@dp.message_handler()
+async def message_handler(message: types.Message) -> None:
+    await SendMessage(chat_id=message.from_user.id, text=message.text)
+```
+
+
+## Including routers
+Example:
+```python3
+dp = Dispatcher()
+router1 = Router()
+dp.include_router(router1)
+```
+
+
+## Handling updates
+All updates can be propagated to the dispatcher by `feed_update` method:
+
+```
+bot = Bot(...)
+dp = Dispathcher()
+
+...
+
+async for result in dp.feed_update(bot=bot, update=incoming_update):
+    print(result)
+```
+
+**Method specification**:
+
+| Argument | Type | Description |
+| --- | --- | --- |
+| `bot` | `Bot` | Bot instance related with current update object |
+| `update` | `Update` | Update object |
+| `**kwargs` | `Any` | Context related data. Will be propagated to handlers, filters and middlewares  |
+
+### Polling
+...
+
+### Webhook
+...

docs/dispatcher/filters/index.md

@@ -0,0 +1,7 @@
+# Overview
+
+
+## Writing own filters
+
+
+## Builtin filters

docs/dispatcher/index.md

@@ -0,0 +1,13 @@
+# Overview
+
+Dispatcher is needed for handling incoming updates from Telegram. With dispatcher you can do:
+
+- Handle incoming updates;
+- Filter incoming events before it will be processed by specific handler;
+- Modify event and related data in middlewares;
+- Separate bot functionality between different handlers, modules and packages
+
+Manually dispatcher has the router role and can include another routers.
+
+Dispatcher is also separated into two entities - Router and Dispatcher.
+Dispatcher is subclass of router and should be always is root router.

docs/dispatcher/observer.md

@@ -0,0 +1,54 @@
+# 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:
+
+1. [EventObserver](#eventobserver) 
+1. [TelegramEventObserver](#telegrameventobserver)
+
+
+## EventObserver
+Reference: `#!python3 aiogram.dispatcher.event.observer.EventObserver`
+
+That is base observer for all events.
+
+### Base registering method
+Method: `<observer>.register(callback, filter1, filter2, ...)`
+
+| Argument | Type | Description |
+| --- | --- | --- |
+| `callback` | `#!python3 Callable[[Any], Awaitable[Any]]` | Event handler |
+| `*filters` | `#!python3 Union[Callable[[Any], Any], Callable[[Any], Awaitable[Any]], BaseFilter]` | Ordered filters set |
+
+Will return original callback.
+
+
+### Decorator-style registering method
+
+Usage:
+```python3
+@<observer>(filter1, filter2, ...)
+async def handler(*args, **kwargs):
+    pass
+```
+
+## TelegramEventObserver
+Is subclass of [EventObserver](#eventobserver) with some differences.
+In this handler can be bounded filters which can be used as keyword arguments instead of writing full references when you register new handlers.
+
+### Registering bound filters
+
+Bound filter should be subclass of [BaseFilter](filters/base_filter.md)
+
+`#!python3 <observer>.bind_filter(MyFilter)`
+
+### Registering handlers
+Method: `EventObserver.register(callback, filter1, filter2, ..., bound_filter=value, ...)`
+In this method is added bound filters keywords interface.
+
+| Argument | Type | Description |
+| --- | --- | --- |
+| `callback` | `#!python3 Callable[[Any], Awaitable[Any]]` | Event handler |
+| `*filters` | `#!python3 Union[Callable[[Any], Any], Callable[[Any], Awaitable[Any]], BaseFilter]` | Ordered filters set |
+| `**bound_filters` | `#!python3 Any` | Bound filters |

docs/dispatcher/router.md

@@ -0,0 +1,137 @@
+# Router
+Imports:
+
+- Recommended: `#!python3 from aiogram import Dispatcher`
+- Real location: `#!python3 from aiogram.dispatcher.dispatcher import Dispatcher`
+
+Router does not accept any arguments in initializer so that's mean you can simply create instance:
+```python3
+router = Router()
+```
+
+Router can route update and it nested update types like messages, callback query, polls and all other event types.
+
+## Event observers
+Here is used event-observer pattern. (Read more on [observer page >>](observer.md))
+
+Event handlers can be registered in observer by two ways:
+
+1. By observer method - `#!python3 router.<event_type>.register(handler, <filters, ...>)`
+1. By decorator - `#!python3 @router.<event_type>(<filters, ...>)`
+
+!!! warning
+    
+    All handlers is always should be an asynchronous.
+    Name of handler function is not important. Event argument name is also is not important but is recommended to don't overlap the name with contextual data in due to function can not accept two arguments with the same name.  
+
+Here is list of available observers and examples how to register handlers (In examples used only @decorator-style):
+
+### Update
+```python3
+@router.update_handler():
+async def message_handler(update: types.Update) -> Any: pass
+```
+Should be used for handling [updates](../api/types/update.md). By default Router is already have an update handler which route all event types to another observers.
+
+### Message
+```python3
+@router.message_handler():
+async def message_handler(message: types.Message) -> Any: pass
+```
+Is useful for handling [message](../api/types/message.md)
+
+### Edited message
+```python3
+@router.edited_message_handler():
+async def edited_message_handler(edited_message: types.Message) -> Any: pass
+```
+Is useful for handling [edited messages](../api/types/message.md)
+
+### Channel post
+```python3
+@router.channel_post_handler():
+async def channel_post_handler(channel_post: types.Message) -> Any: pass
+```
+Is useful for handling [channel posts](../api/types/message.md)
+
+### Edited channel post
+```python3
+@router.edited_channel_post_handler():
+async def edited_channel_post_handler(edited_channel_post: types.Message) -> Any: pass
+```
+Is useful for handling [edited channel posts](../api/types/message.md)
+
+### Inline query
+```python3
+@router.inline_query_handler():
+async def inline_query_handler(inline_query: types.Message) -> Any: pass
+```
+Is useful for handling [inline query](../api/types/inline_query.md)
+
+### Chosen inline query
+```python3
+@router.chosen_inline_result_handler():
+async def chosen_inline_result_handler(chosen_inline_result: types.ChosenInlineResult) -> Any: pass
+```
+Is useful for handling [chosen inline query](../api/types/chosen_inline_result.md)
+
+### Callback query
+```python3
+@router.callback_query_handler():
+async def callback_query_handler(callback_query: types.CallbackQuery) -> Any: pass
+```
+Is useful for handling [callback query's](../api/types/callback_query.md)
+
+### Shipping query
+```python3
+@router.shipping_query_handler():
+async def shipping_query_handler(shipping_query: types.ShippingQuery) -> Any: pass
+```
+Is useful for handling [shipping query](../api/types/shipping_query.md)
+
+### Pre checkout query
+```python3
+@router.pre_checkout_query_handler():
+async def pre_checkout_query_handler(pre_checkout_query: types.PreCheckoutQuery) -> Any: pass
+```
+Is useful for handling [pre-checkout query](../api/types/pre_checkout_query.md)
+
+### Poll
+```python3
+@router.poll_handler():
+async def poll_handler(poll: types.Poll) -> Any: pass
+```
+Is useful for handling [polls](../api/types/poll.md)
+
+
+## Nested routers
+
+!!! warning
+    Routers by the way can be nested to an another routers with some limitations:
+    
+    1. Router **CAN NOT** include itself
+    1. Routers **CAN NOT** be used for circular including (router 1 include router 2, router 2 include router 3, router 3 include router 1)
+
+
+Example:
+```python3
+# module_1.py
+router1 = Router()
+router2 = Router()
+
+router2.include_router(router1)
+```
+
+
+## How it works?
+
+For example dispatcher has 2 routers, last one router is also have one nested router:
+
+[![nested routers example](../assets/images/nested_routers_example.png)](../assets/images/nested_routers_example.png)
+_(Click on image to zoom it)_
+
+In this case update propagation flow will have form:
+
+[![update propagation flow](../assets/images/update_propagation_flow.png)](../assets/images/update_propagation_flow.png)
+_(Click on image to zoom it)_
+

mkdocs.yml

@@ -217,6 +217,15 @@ nav:
               - api/types/callback_game.md
               - api/types/game_high_score.md
       - api/sending_files.md
+  - Dispatcher:
+      - dispatcher/index.md
+      - dispatcher/router.md
+      - dispatcher/dispatcher.md
+      - dispatcher/observer.md
+      - Filters:
+          - dispatcher/filters/index.md
+          - dispatcher/filters/base_filter.md
+
   - Build reports:
       - reports.md
       - Tests result: /reports/tests