Docs/update (#69)

* docs: minor fix

* examples directory changed

* docs: expand descriptions in the script

* docs: expand descriptions in pipeline

* docs: expand descriptions in messengers

* docs: expand descriptions in context storages

* docs: add descriptions of each element in the tocs

* docs: fix links to py class

* docs: corrections

* Update dff/context_storages/mongo.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* Update dff/context_storages/protocol.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* Update dff/context_storages/redis.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* Update dff/context_storages/sql.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* Update dff/context_storages/sql.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* Update dff/pipeline/pipeline/pipeline.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* Update dff/pipeline/pipeline/pipeline.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* Update dff/script/core/context.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* Update dff/script/core/context.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* Update dff/script/core/keywords.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* Update dff/script/core/message.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* Update dff/script/core/keywords.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* docs: json.py module fixes

* docs: add installation options

* docs: rewrite service.py description

* docs: add TODO

* docs: pipeline conditions description

* docs: remove double whitespace

* docs: replace db connectors to context storages

* Update dff/messengers/common/interface.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* Update dff/messengers/common/types.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* Update dff/pipeline/pipeline/pipeline.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* Update dff/pipeline/pipeline/pipeline.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* Update dff/pipeline/pipeline/pipeline.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* Update dff/pipeline/service/group.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* Update dff/pipeline/pipeline/pipeline.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* docs: add TODO

* Update dff/pipeline/types.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* Update dff/script/core/actor.py

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* docs: fix in make clean description

* Update docs/source/index.rst

Co-authored-by: Kuznetsov Denis <kuznetsov.den.p@gmail.com>

* docs: update info about installation

* docs: fix in script description

* docs: fix in the toc description

* docs: fix code block display

* docs: fix naming

* docs: fix toc rendering

* Update dff/pipeline/service/group.py

* docs: add information about team

* docs: remove unimportant sections

* docs: fix text format

---------

Co-authored-by: Denis Kuznetsov <kuznetsov.den.p@gmail.com>

README.md

@@ -26,6 +26,7 @@ pip install dff
 The above command will set the minimum dependencies to start working with DFF. 
 The installation process allows the user to choose from different packages based on their dependencies, which are:
 ```bash
+pip install dff[core]  # minimal dependencies (by default)
 pip install dff[redis]  # dependencies for using Redis
 pip install dff[mongodb]  # dependencies for using MongoDB
 pip install dff[mysql]  # dependencies for using MySQL

dff/context_storages/database.py

@@ -1,8 +1,11 @@
 """
 Database
 --------
-Base module. Provided classes:
-    - Abstract context storage interface :py:class:`.DBContextStorage`.
+The `Database` module provides classes for managing the context storage of a dialog system.
+The module can be used to store information such as the current state of the conversation
+and other data. This module includes the intermediate class (:py:class:`.DBContextStorage`) is a class
+that developers can inherit from in order to create their own context storage solutions.
+This class implements the basic functionality and can be extended to add additional features as needed.
 """
 import asyncio
 import importlib

dff/context_storages/json.py

@@ -1,7 +1,9 @@
 """
 JSON
-----
-Provides the json-based version of the :py:class:`.DBContextStorage`.
+-----
+The JSON module provides a json-based version of the :py:class:`.DBContextStorage` class.
+This class is used to store and retrieve context data in a JSON. It allows the `DFF` to easily
+store and retrieve context data.
 """
 import asyncio
 from typing import Hashable

dff/context_storages/mongo.py

@@ -1,7 +1,15 @@
 """
 Mongo
 -----
-Provides the mongo-based version of the :py:class:`.DBContextStorage`.
+The Mongo module provides a MongoDB-based version of the :py:class:`.DBContextStorage` class.
+This class is used to store and retrieve context data in a MongoDB.
+It allows the `DFF` to easily store and retrieve context data in a format that is highly scalable
+and easy to work with.
+
+MongoDB is a widely-used, open-source NoSQL database that is known for its scalability and performance.
+It stores data in a format similar to JSON, making it easy to work with the data in a variety of programming languages
+and environments. Additionally, MongoDB is highly scalable and can handle large amounts of data
+and high levels of read and write traffic.
 """
 from typing import Hashable, Dict
 

dff/context_storages/pickle.py

@@ -1,7 +1,14 @@
 """
 Pickle
 ------
-Provides the pickle-based version of the :py:class:`.DBContextStorage`.
+The Pickle module provides a pickle-based version of the :py:class:`.DBContextStorage` class.
+This class is used to store and retrieve context data in a pickle format.
+It allows the `DFF` to easily store and retrieve context data in a format that is efficient
+for serialization and deserialization and can be easily used in python.
+
+Pickle is a python library that allows to serialize and deserialize python objects.
+It is efficient and fast, but it is not recommended to use it to transfer data across
+different languages or platforms because it's not cross-language compatible.
 """
 import asyncio
 import pickle

dff/context_storages/protocol.py

@@ -1,8 +1,16 @@
 """
 Protocol
 --------
-Base protocol code. Protocols :py:data:`.PROTOCOLS`.
-A func is used for suggestion of installation: :py:func:`.get_protocol_install_suggestion`.
+The Protocol module contains the base code for the different communication protocols used in the `DFF`.
+It defines the :py:data:`.PROTOCOLS` constant, which lists all the supported protocols in the `DFF`.
+
+The module also includes a function :py:func:`.get_protocol_install_suggestion()` that is used to provide
+suggestions for installing the necessary dependencies for a specific protocol.
+This function takes the name of the desired protocol as an argument and returns
+a string containing the necessary installation commands for that protocol.
+
+The `DFF` supports a variety of communication protocols,
+which allows it to communicate with different types of databases.
 """
 import json
 import pathlib

dff/context_storages/redis.py

@@ -1,7 +1,16 @@
 """
 Redis
 -----
-Provides the redis-based version of the :py:class:`.DBContextStorage`.
+The Redis module provides a Redis-based version of the :py:class:`.DBContextStorage` class.
+This class is used to store and retrieve context data in a Redis.
+It allows the `DFF` to easily store and retrieve context data in a format that is highly scalable
+and easy to work with.
+
+Redis is an open-source, in-memory data structure store that is known for its
+high performance and scalability. It stores data in key-value pairs and supports a variety of data
+structures such as strings, hashes, lists, sets, and more.
+Additionally, Redis can be used as a cache, message broker, and database, making it a versatile
+and powerful choice for data storage and management.
 """
 import json
 from typing import Hashable

dff/context_storages/shelve.py

@@ -1,7 +1,16 @@
 """
 Shelve
 ------
-Provides the shelve-based version of the :py:class:`.DBContextStorage`.
+The Shelve module provides a shelve-based version of the :py:class:`.DBContextStorage` class.
+This class is used to store and retrieve context data in a shelve format.
+It allows the `DFF` to easily store and retrieve context data in a format that is efficient
+for serialization and deserialization and can be easily used in python.
+
+Shelve is a python library that allows to store and retrieve python objects.
+It is efficient and fast, but it is not recommended to use it to transfer data across different languages
+or platforms because it's not cross-language compatible.
+It stores data in a dbm-style format in the file system, which is not as fast as the other serialization
+libraries like pickle or JSON.
 """
 import pickle
 from shelve import DbfilenameShelf

dff/context_storages/sql.py

@@ -1,8 +1,16 @@
 """
 SQL
 ---
-Provides the SQL-based version of the :py:class:`.DBContextStorage`.
-You can choose the backend option of your liking from MySQL, PostgreSQL, or SQLite.
+The SQL module provides a SQL-based version of the :py:class:`.DBContextStorage` class.
+This class is used to store and retrieve context data from SQL databases.
+It allows the `DFF` to easily store and retrieve context data in a format that is highly scalable
+and easy to work with.
+
+The SQL module provides the ability to choose the backend of your choice from
+MySQL, PostgreSQL, or SQLite. You can choose the one that is most suitable for your use case and environment.
+MySQL and PostgreSQL are widely used open-source relational databases that are known for their
+reliability and scalability. SQLite is a self-contained, high-reliability, embedded, full-featured,
+public-domain, SQL database engine.
 """
 import asyncio
 import importlib

dff/context_storages/ydb.py

@@ -1,7 +1,13 @@
 """
 Yandex DB
 ---------
-Provides the version of the :py:class:`.DBContextStorage` for Yandex DataBase.
+The Yandex DB module provides a version of the :py:class:`.DBContextStorage` class that designed to work with
+Yandex and other databases. Yandex DataBase is a fully-managed cloud-native SQL service that makes it easy to set up,
+operate, and scale high-performance and high-availability databases for your applications.
+
+The Yandex DB module uses the Yandex Cloud SDK, which is a python library that allows you to work
+with Yandex Cloud services using python. This allows the DFF to easily integrate with the Yandex DataBase and
+take advantage of the scalability and high-availability features provided by the service.
 """
 import asyncio
 import os

dff/messengers/common/interface.py

@@ -1,7 +1,8 @@
 """
 Message Interfaces
 ------------------
-This module contains several basic classes of message interfaces.
+The Message Interfaces module contains several basic classes that define the message interfaces.
+These classes provide a way to define the structure of the messengers that are used to communicate with the `DFF`.
 """
 import abc
 import asyncio

dff/messengers/common/types.py

@@ -1,8 +1,9 @@
 """
 Types
 -----
-This module contains two special types.
-One is used for the messenger interface to client interaction, the other to the polling loop control.
+The Types module contains two special types that are used throughout the `DFF Messengers`.
+The first type is used for the messenger interface to client interaction and the second one
+to control the polling loop.
 """
 from typing import Callable, Any, Hashable, Awaitable
 from typing_extensions import TypeAlias
@@ -13,7 +14,7 @@
 PipelineRunnerFunction: TypeAlias = Callable[[Any, Hashable], Awaitable[Context]]
 """
 A function type for messenger_interface-to-client interaction.
-Accepts anything (user input) and hashable vaklue (current dialog id), returns string (answer from pipeline).
+Accepts anything (user input) and hashable value (current context id), returns string (answer from pipeline).
 """
 
 

dff/pipeline/conditions.py

@@ -1,6 +1,9 @@
 """
 Conditions
 ----------
+The conditions module contains functions that can be used to determine whether the pipeline component to which they
+are attached should be executed or not.
+The standard set of them allows user to setup dependencies between pipeline components.
 """
 from typing import Optional
 

dff/pipeline/pipeline/component.py

@@ -1,7 +1,12 @@
 """
 Component
 ---------
-The PipelineComponent class is defined in this module.
+The Component module defines a :py:class:`.PipelineComponent` class,
+which is a fundamental building block of the framework. A PipelineComponent represents a single
+step in a processing pipeline, and is responsible for performing a specific task or set of tasks.
+
+The PipelineComponent class can be a group or a service. It is designed to be reusable and composable,
+allowing developers to create complex processing pipelines by combining multiple components.
 """
 import logging
 import abc

dff/pipeline/pipeline/pipeline.py

@@ -1,7 +1,17 @@
 """
 Pipeline
 --------
-This module contains the Pipeline class.
+The Pipeline module contains the :py:class:`.Pipeline` class,
+which is a fundamental element of the `DFF`. The Pipeline class is responsible
+for managing and executing the various components (:py:class:`.PipelineComponent`)which make up
+the processing of messages from and to users.
+It provides a way to organize and structure the messages processing flow.
+The Pipeline class is designed to be highly customizable and configurable,
+allowing developers to add, remove, or modify the components that make up the messages processing flow.
+
+The Pipeline class is designed to be used in conjunction with the :py:class:`.PipelineComponent`
+class, which is defined in the Component module. Together, these classes provide a powerful and flexible way
+to structure and manage the messages processing flow.
 """
 import asyncio
 import logging

dff/pipeline/pipeline/utils.py

@@ -1,7 +1,8 @@
 """
 Utils
 -----
-This module contains several service functions.
+The Utils module contains several service functions that are commonly used throughout the framework.
+These functions provide a variety of utility functionality.
 """
 import collections
 from typing import Union, List, Callable

dff/pipeline/service/extra.py

@@ -1,6 +1,9 @@
 """
 Extra Handler
 -------------
+The Extra Handler module contains additional functionality that extends the capabilities of the system
+beyond the core functionality. Extra handlers is an input converting addition to :py:class:`.PipelineComponent`.
+For examples, it is used to grep statistics from components, timeing, logging, etc.
 """
 import asyncio
 import logging

dff/pipeline/service/group.py

@@ -1,7 +1,11 @@
 """
 Service Group
 -------------
-This module contatins `ServiceGroup` class. This class represents a service group.
+The Service Group module contains the
+:py:class:`~.ServiceGroup` class, which is used to represent a group of related services.
+This class provides a way to organize and manage multiple services as a single unit,
+allowing for easier management and organization of the services within the pipeline.
+The :py:class:`~.ServiceGroup` serves the important function of grouping services to work together in parallel.
 """
 import asyncio
 import logging

dff/pipeline/service/service.py

@@ -1,8 +1,16 @@
 """
-Service Class
--------------
-This module contains `Service` class. A description of the class is given below.
+Service
+-------
+The Service module contains the :py:class:`.Service` class,
+which can be included into pipeline as object or a dictionary.
+Pipeline consists of services and service groups.
+Service group can be synchronous or asynchronous.
+Service is an atomic part of a pipeline.
+Service can be asynchronous only if its handler is a coroutine.
+Actor wrapping service can be synchronous only.
 """
+# TODO: change last sentence, when actor will be asynchronous
+
 import logging
 import asyncio
 import inspect

dff/pipeline/service/utils.py

@@ -1,7 +1,8 @@
 """
 Utility Functions
 -----------------
-These module contains several utility functions.
+The Utility Functions module contains several utility functions that are commonly used throughout the `DFF`.
+These functions provide a variety of utility functionality.
 """
 import asyncio
 from typing import Callable, Any, Optional, Tuple, Mapping

dff/pipeline/types.py

@@ -1,7 +1,9 @@
 """
 Types
 -----
-This module contains several classes and special types (see below).
+The Types module contains several classes and special types that are used throughout the `DFF Pipeline`.
+The classes and special types in this module can include data models,
+data structures, and other types that are defined for type hinting.
 """
 from abc import ABC
 from enum import unique, Enum, auto

dff/script/conditions/std_conditions.py

@@ -1,9 +1,12 @@
 """
 Conditions
----------------------------
-Conditions are one of the most important components of the dialog graph,
-which determine the possibility of transition from one node of the graph to another.
-This is a standard set of scripting conditions.
+----------
+Conditions are one of the most important components of the dialog graph.
+They determine the possibility of transition from one node of the graph to another.
+The conditions are used to specify when a particular transition should occur, based on certain criteria.
+This module contains a standard set of scripting conditions that can be used to control the flow of a conversation.
+These conditions can be used to check the current context, the user's input,
+or other factors that may affect the conversation flow.
 """
 from typing import Callable, Pattern, Union, Any, List, Optional
 import logging
@@ -21,10 +24,10 @@ def exact_match(match: Message, skip_none: bool = True, *args, **kwargs) -> Call
     """
     Returns function handler. This handler returns `True` only if the last user phrase
     is the same Message as the :py:const:`match`.
-    If :py:const:`skip_none` the handler will not compare None fields of :py:const:`match`.
+    If :py:const:`skip_none` the handler will not compare `None` fields of :py:const:`match`.
 
     :param match: A Message variable to compare user request with.
-    :param skip_none: Whether fields should be compared if they are None in :py:const:`match`.
+    :param skip_none: Whether fields should be compared if they are `None` in :py:const:`match`.
     """
 
     def exact_match_condition_handler(ctx: Context, actor: Actor, *args, **kwargs) -> bool:

dff/script/core/actor.py

@@ -1,9 +1,21 @@
 """
 Actor
----------------------------
-Actor is one of the main abstractions that processes incoming requests
-(:py:class:`~dff.script.Context`)
-from the user in accordance with the dialog graph (:py:class:`~dff.script.Script`).
+-----
+Actor is a component of :py:class:`.Pipeline`, that contains the :py:class:`.Script` and handles it.
+It is responsible for processing user input and determining the appropriate response based
+on the current state of the conversation and the script.
+The actor receives requests in the form of a :py:class:`.Context` class, which contains
+information about the user's input, the current state of the conversation, and other relevant data.
+
+The actor uses the dialog graph, represented by the :py:class:`.Script` class,
+to determine the appropriate response. The script contains the structure of the conversation,
+including the different `nodes` and `transitions`.
+It defines the possible paths that the conversation can take, and the conditions that must be met
+for a transition to occur. The actor uses this information to navigate the graph
+and determine the next step in the conversation.
+
+Overall, the actor acts as a bridge between the user's input and the dialog graph,
+making sure that the conversation follows the expected flow and providing a personalized experience to the user.
 """
 import logging
 from typing import Union, Callable, Optional, Dict, List, Any