deeppavlov · RLKRo · Oct 2, 2023 · Apr 27, 2023 · Apr 27, 2023 · May 27, 2023
diff --git a/docs/source/utils/notebook.py b/docs/source/utils/notebook.py
@@ -16,23 +16,18 @@ def inner(tutorial_text: str):
 # %% [markdown]
 \"\"\"
 __Installing dependencies__
+
+The cell below installs dff with dependencies for running tutorials
+To install the minimal version of dff, use `pip install dff`
+To install other options of dff, use `pip install dff[OPTION_NAME1,OPTION_NAME2]`
+where OPTION_NAME can be one of the options from EXTRA_DEPENDENCIES.
+e.g `pip install dff[ydb, mysql]` installs dff with dependencies for using Yandex Database and MySQL
+EXTRA_DEPENDENCIES can be found in
+[here](https://github.com/deeppavlov/dialog_flow_framework/blob/dev/README.md#installation)
 \"\"\"
 
 # %%
 !python3 -m pip install -q dff[tutorials]
-# Installs dff with dependencies for running tutorials
-# To install the minimal version of dff, use `pip install dff`
-# To install other options of dff, use `pip install dff[OPTION_NAME1,OPTION_NAME2]`
-# where OPTION_NAME can be one of the options from EXTRA_DEPENDENCIES.
-# e.g `pip install dff[ydb, mysql]` installs dff with dependencies for using Yandex Database and MySQL
-# EXTRA_DEPENDENCIES can be found in
-# https://github.com/deeppavlov/dialog_flow_framework/blob/dev/README.md#installation
-
-
-# %% [markdown]
-\"\"\"
-__Running tutorial__
-\"\"\"
 
 {tutorial_text[second_cell:]}
 """,

diff --git a/tests/tutorials/test_format.py b/tests/tutorials/test_format.py
@@ -13,7 +13,7 @@
     re.compile(r"# %%\n"),  # check python block
 ]
 
-docstring_start_pattern = re.compile(r'# %% \[markdown\]\n"""\n#(?: .*:)? \d+\. .*\n(?:\n[\S\s]*)?"""\n')
+docstring_start_pattern = re.compile(r'# %% \[markdown\]\n"""\n#(?: .*:)? \d+\. .*\n(?:\n[\S\s]*)?"""(?:  # .*)?\n')
 comment_start_pattern = re.compile(r'# %% \[markdown\]\n# #(?: .*:)? \d+\. .*\n#(?:\n# [\S\s]*)?')
 
 

diff --git a/tutorials/context_storages/1_basics.py b/tutorials/context_storages/1_basics.py
@@ -3,7 +3,12 @@
 # 1. Basics
 
 The following tutorial shows the basic use of the database connection.
-"""
+
+See [context_storage_factory](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.context_storages.database.html#dff.context_storages.database.context_storage_factory) function
+for creating a context storage factory by path.
+
+In this example JSON file is used as a storage.
+"""  # noqa: E501
 
 
 # %%

diff --git a/tutorials/context_storages/2_postgresql.py b/tutorials/context_storages/2_postgresql.py
@@ -3,7 +3,13 @@
 # 2. PostgreSQL
 
 This is a tutorial on using PostgreSQL.
-"""
+
+See [SQLContextStorage](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.context_storages.sql.html#sql) class
+for storing you users' contexts in SQL databases.
+
+The DFF uses [sqlalchemy](https://docs.sqlalchemy.org/en/20/) and [asyncpg](https://magicstack.github.io/asyncpg/current/)
+libraries for asynchronous access to PostgreSQL DB.
+"""  # noqa: E501
 
 
 # %%

diff --git a/tutorials/context_storages/3_mongodb.py b/tutorials/context_storages/3_mongodb.py
@@ -3,7 +3,12 @@
 # 3. MongoDB
 
 This is a tutorial on using MongoDB.
-"""
+
+See [MongoContextStorage](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.context_storages.mongo.html#mongo) class
+for storing you users' contexts in Mongo database.
+
+The DFF uses [motor](https://motor.readthedocs.io/en/stable/) library for asynchronous access to MongoDB.
+"""  # noqa: E501
 
 
 # %%

diff --git a/tutorials/context_storages/4_redis.py b/tutorials/context_storages/4_redis.py
@@ -3,7 +3,12 @@
 # 4. Redis
 
 This is a tutorial on using Redis.
-"""
+
+See [RedisContextStorage](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.context_storages.redis.html#redis) class
+for storing you users' contexts in Redis database.
+
+The DFF uses [redis.asyncio](https://redis.readthedocs.io/en/latest/) library for asynchronous access to Redis DB.
+"""  # noqa: E501
 
 
 # %%

diff --git a/tutorials/context_storages/5_mysql.py b/tutorials/context_storages/5_mysql.py
@@ -3,7 +3,13 @@
 # 5. MySQL
 
 This is a tutorial on using MySQL.
-"""
+
+See [MySQL](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.context_storages.sql.html#sql) class
+for storing you users' contexts in SQL databases.
+
+The DFF uses [sqlalchemy](https://docs.sqlalchemy.org/en/20/) and [asyncmy](https://github.com/long2ice/asyncmy)
+libraries for asynchronous access to MySQL DB.
+"""  # noqa: E501
 
 
 # %%

diff --git a/tutorials/context_storages/6_sqlite.py b/tutorials/context_storages/6_sqlite.py
@@ -3,7 +3,15 @@
 # 6. SQLite
 
 This is a tutorial on using SQLite.
-"""
+
+See [SQLite](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.context_storages.sql.html#sql) class
+for storing you users' contexts in SQL databases.
+
+The DFF uses [sqlalchemy](https://docs.sqlalchemy.org/en/20/) and [aiosqlite](https://readthedocs.org/projects/aiosqlite/)
+libraries for asynchronous access to SQLite DB.
+
+Note that protocol separator for windows differs from one for linux.
+"""  # noqa: E501
 
 
 # %%

diff --git a/tutorials/context_storages/7_yandex_database.py b/tutorials/context_storages/7_yandex_database.py
@@ -3,7 +3,12 @@
 # 7. Yandex DataBase
 
 This is a tutorial on how to use Yandex DataBase.
-"""
+
+See [YDB](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.context_storages.ydb.html#yandex-db) class
+for storing you users' contexts in Yandex database.
+
+The DFF uses [ydb.aio](https://ydb.tech/en/docs/) library for asynchronous access to Yandex DB.
+"""  # noqa: E501
 
 
 # %%

diff --git a/tutorials/messengers/telegram/1_basic.py b/tutorials/messengers/telegram/1_basic.py
@@ -4,7 +4,12 @@
 
 The following tutorial shows how to run a regular DFF script in Telegram.
 It asks users for the '/start' command and then loops in one place.
-"""
+
+Here, [PollingTelegramInterface](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.common.interface.html#dff.messengers.common.interface.PollingMessengerInterface)
+class and [telebot](https://pytba.readthedocs.io/en/latest/index.html) library are used for accessing telegram API in polling mode.
+
+Telegram API token is used for access telegram API.
+"""  # noqa: E501
 
 
 # %%

diff --git a/tutorials/messengers/telegram/2_buttons.py b/tutorials/messengers/telegram/2_buttons.py
@@ -2,9 +2,17 @@
 """
 # Telegram: 2. Buttons
 
-
 This tutorial shows how to display and hide a basic keyboard in Telegram.
-"""
+
+Here, [TelegramMessage](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.telegram.message.html#telegram-message)
+class is used to represent telegram message, [TelegramUI](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.telegram.message.html#dff.messengers.telegram.message.TelegramUI) and
+[RemoveKeyboard](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.telegram.message.html#dff.messengers.telegram.message.RemoveKeyboard)
+classes are used for configuring additional telegram message features.
+
+Different [message](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.script.core.message.html#message)
+classes are used for representing different common message features, like Attachment, Audio, Button, Image, etc.
+"""  # noqa: E501
+
 
 # %%
 import os

diff --git a/tutorials/messengers/telegram/3_buttons_with_callback.py b/tutorials/messengers/telegram/3_buttons_with_callback.py
@@ -2,10 +2,18 @@
 """
 # Telegram: 3. Buttons with Callback
 
-
 This tutorial demonstrates, how to add an inline keyboard and utilize
 inline queries.
-"""
+
+Here, [TelegramMessage](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.telegram.message.html#telegram-message)
+class is used to represent telegram message, [TelegramUI](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.telegram.message.html#dff.messengers.telegram.message.TelegramUI) and
+[RemoveKeyboard](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.telegram.message.html#dff.messengers.telegram.message.RemoveKeyboard)
+classes are used for configuring additional telegram message features.
+
+Different [message](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.script.core.message.html#message)
+classes are used for representing different common message features, like Attachment, Audio, Button, Image, etc.
+"""  # noqa: E501
+
 
 # %%
 import os

diff --git a/tutorials/messengers/telegram/4_conditions.py b/tutorials/messengers/telegram/4_conditions.py
@@ -4,7 +4,16 @@
 
 This tutorial shows how to process Telegram updates in your script
 and reuse handler triggers from the `pytelegrambotapi` library.
-"""
+
+Here, [TelegramMessage](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.telegram.message.html#telegram-message)
+class is used to represent telegram message, [TelegramUI](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.telegram.message.html#dff.messengers.telegram.message.TelegramUI) and
+[RemoveKeyboard](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.telegram.message.html#dff.messengers.telegram.message.RemoveKeyboard)
+classes are used for configuring additional telegram message features.
+
+Different [message](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.script.core.message.html#message)
+classes are used for representing different common message features, like Attachment, Audio, Button, Image, etc.
+"""  # noqa: E501
+
 
 # %%
 import os

diff --git a/tutorials/messengers/telegram/5_conditions_with_media.py b/tutorials/messengers/telegram/5_conditions_with_media.py
@@ -3,7 +3,16 @@
 # Telegram: 5. Conditions with Media
 
 This tutorial shows how to use media-related logic in your script.
-"""
+
+Here, [TelegramMessage](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.telegram.message.html#telegram-message)
+class is used to represent telegram message, [TelegramUI](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.telegram.message.html#dff.messengers.telegram.message.TelegramUI) and
+[RemoveKeyboard](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.telegram.message.html#dff.messengers.telegram.message.RemoveKeyboard)
+classes are used for configuring additional telegram message features.
+
+Different [message](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.script.core.message.html#message)
+classes are used for representing different common message features, like Attachment, Audio, Button, Image, etc.
+"""  # noqa: E501
+
 
 # %%
 import os

diff --git a/tutorials/messengers/telegram/6_conditions_extras.py b/tutorials/messengers/telegram/6_conditions_extras.py
@@ -4,7 +4,20 @@
 
 This tutorial shows how to use additional update filters
 inherited from the `pytelegrambotapi` library.
-"""
+
+Here, [TelegramMessage](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.telegram.message.html#telegram-message)
+class is used to represent telegram message, [TelegramUI](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.telegram.message.html#dff.messengers.telegram.message.TelegramUI) and
+[RemoveKeyboard](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.telegram.message.html#dff.messengers.telegram.message.RemoveKeyboard)
+classes are used for configuring additional telegram message features.
+
+Different [message](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.script.core.message.html#message)
+classes are used for representing different common message features, like Attachment, Audio, Button, Image, etc.
+
+[telegram_condition](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.telegram.messenger.html#dff.messengers.telegram.messenger.telegram_condition)
+function and different types of [UpdateType](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.telegram.messenger.html#dff.messengers.telegram.messenger.UpdateType)
+can be used for telegram message type checking.
+"""  # noqa: E501
+
 
 # %%
 import os

diff --git a/tutorials/messengers/telegram/7_polling_setup.py b/tutorials/messengers/telegram/7_polling_setup.py
@@ -4,7 +4,9 @@
 
 The following tutorial shows how to configure `PollingTelegramInterface`.
 
-"""
+Here, [PollingTelegramInterface](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.common.interface.html#dff.messengers.common.interface.PollingMessengerInterface)
+and its' different parameters are shown.
+"""  # noqa: E501
 
 
 # %%

diff --git a/tutorials/messengers/telegram/8_webhook_setup.py b/tutorials/messengers/telegram/8_webhook_setup.py
@@ -4,7 +4,10 @@
 
 The following tutorial shows how to use `CallbackTelegramInterface`
 that makes your bot accessible through a public webhook.
-"""
+
+Here, [PollingTelegramInterface](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.messengers.common.interface.html#dff.messengers.common.interface.CallbackMessengerInterface)
+is used for accessing telegram API in callback mode.
+"""  # noqa: E501
 
 
 # %%

diff --git a/tutorials/messengers/web_api_interface/1_fastapi.py b/tutorials/messengers/web_api_interface/1_fastapi.py
@@ -5,7 +5,13 @@
 This tutorial shows how to create an API for DFF using FastAPI.
 
 You can see the result at http://127.0.0.1:8000/docs.
-"""
+
+Here, `_run_pipeline` (same as [run](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.pipeline.pipeline.pipeline.html#dff.pipeline.pipeline.pipeline.Pipeline.run))
+method is used to execute pipeline once.
+
+[Message](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.script.core.message.html#dff.script.core.message.Message)
+is used to represent incoming to pipeline data.
+"""  # noqa: E501
 
 
 # %%

diff --git a/tutorials/messengers/web_api_interface/2_websocket_chat.py b/tutorials/messengers/web_api_interface/2_websocket_chat.py
@@ -14,7 +14,13 @@
 > ... for this example, we'll use a very simple HTML document with some JavaScript,
 > all inside a long string.
 > This, of course, is not optimal and you wouldn't use it for production.
-"""
+
+Here, `_run_pipeline` (same as [run](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.pipeline.pipeline.pipeline.html#dff.pipeline.pipeline.pipeline.Pipeline.run))
+method is used to execute pipeline once.
+
+[Message](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.script.core.message.html#dff.script.core.message.Message)
+is used to represent incoming to pipeline data.
+"""  # noqa: E501
 
 
 # %%

diff --git a/tutorials/pipeline/1_basics.py b/tutorials/pipeline/1_basics.py
@@ -4,7 +4,10 @@
 
 The following tutorial shows basic usage of `pipeline`
 module as an extension to `dff.script.core`.
-"""
+
+Here, `__call__` (same as [run](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.pipeline.pipeline.pipeline.html#dff.pipeline.pipeline.pipeline.Pipeline.run))
+method is used to execute pipeline once.
+"""  # noqa: E501
 
 
 # %%

diff --git a/tutorials/pipeline/2_pre_and_post_processors.py b/tutorials/pipeline/2_pre_and_post_processors.py
@@ -4,7 +4,10 @@
 
 The following tutorial shows more advanced usage of `pipeline`
 module as an extension to `dff.script.core`.
-"""
+
+Here, [MISC](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.script.core.context.html#dff.script.core.context.Context.misc)
+dictionary of context is used for storing message additional data.
+"""  # noqa: E501
 
 
 # %%

diff --git a/tutorials/pipeline/3_pipeline_dict_with_services_basic.py b/tutorials/pipeline/3_pipeline_dict_with_services_basic.py
@@ -4,7 +4,13 @@
 
 The following tutorial shows `pipeline` creation from
 dict and most important pipeline components.
-"""
+
+Here, [Service](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.pipeline.service.service.html#service)
+class, that can be used for pre- and postprocessing of messages is shown.
+
+Pipeline [from_dict](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.pipeline.pipeline.pipeline.html#dff.pipeline.pipeline.pipeline.Pipeline.from_dict)
+static method can be used for pipeline creation (from dictionary).
+"""  # noqa: E501
 
 
 # %%

diff --git a/tutorials/pipeline/3_pipeline_dict_with_services_full.py b/tutorials/pipeline/3_pipeline_dict_with_services_full.py
@@ -4,7 +4,13 @@
 
 The following tutorial shows `pipeline` creation from dict
 and most important pipeline components.
-"""
+
+Here, [Service](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.pipeline.service.service.html#service)
+class, that can be used for some more complex pre- and postprocessing of messages is shown.
+
+Pipeline [from_dict](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.pipeline.pipeline.pipeline.html#dff.pipeline.pipeline.pipeline.Pipeline.from_dict)
+static method can be used for pipeline creation (from dictionary).
+"""  # noqa: E501
 
 
 # %%

diff --git a/tutorials/pipeline/4_groups_and_conditions_basic.py b/tutorials/pipeline/4_groups_and_conditions_basic.py
@@ -3,7 +3,11 @@
 # 4. Groups and conditions (basic)
 
 The following example shows `pipeline` service group usage and start conditions.
-"""
+
+Here, [Service](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.pipeline.service.service.html#dff.pipeline.service.service.Service)s
+and [ServiceGroup](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.pipeline.service.group.html#dff.pipeline.service.group.ServiceGroup)s
+are shown for advanced data pre- and postprocessing based on conditions.
+"""  # noqa: E501
 
 
 # %%

diff --git a/tutorials/pipeline/4_groups_and_conditions_full.py b/tutorials/pipeline/4_groups_and_conditions_full.py
@@ -3,7 +3,11 @@
 # 4. Groups and conditions (full)
 
 The following tutorial shows `pipeline` service group usage and start conditions.
-"""
+
+Here, [Service](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.pipeline.service.service.html#dff.pipeline.service.service.Service)s
+and [ServiceGroup](https://deeppavlov.github.io/dialog_flow_framework/apiref/dff.pipeline.service.group.html#dff.pipeline.service.group.ServiceGroup)s
+are shown for advanced data pre- and postprocessing based on conditions.
+"""  # noqa: E501
 
 
 # %%