Enhance keyboard utility, improved documentation page. (#1236)

* Enhance keyboard utility, improved documentation for this utility.

Updated the 'aiogram/utils/keyboard.py' file with new methods for integrating buttons and keyboard creation more seamlessly. Added functionality to create buttons from existing markup and attach another builder. This improvement aims to make the keyboard building process more user-friendly and flexible.

* Added changelog

* Cover by tests

aiogram/utils/keyboard.py

@@ -238,6 +238,12 @@ class KeyboardBuilder(Generic[ButtonType], ABC):
         return self
 
     def button(self, **kwargs: Any) -> "KeyboardBuilder[ButtonType]":
+        """
+        Add button to markup
+
+        :param kwargs:
+        :return:
+        """
         if isinstance(callback_data := kwargs.get("callback_data", None), CallbackData):
             kwargs["callback_data"] = callback_data.pack()
         button = self._button_type(**kwargs)
@@ -250,6 +256,17 @@ class KeyboardBuilder(Generic[ButtonType], ABC):
         inline_keyboard = cast(List[List[InlineKeyboardButton]], self.export())  # type: ignore
         return InlineKeyboardMarkup(inline_keyboard=inline_keyboard)
 
+    def attach(self, builder: "KeyboardBuilder[ButtonType]") -> "KeyboardBuilder[ButtonType]":
+        if not isinstance(builder, KeyboardBuilder):
+            raise ValueError(f"Only KeyboardBuilder can be attached, not {type(builder).__name__}")
+        if builder._button_type is not self._button_type:
+            raise ValueError(
+                f"Only builders with same button type can be attached, "
+                f"not {self._button_type.__name__} and {builder._button_type.__name__}"
+            )
+        self._markup.extend(builder.export())
+        return self
+
 
 def repeat_last(items: Iterable[T]) -> Generator[T, None, None]:
     items_iter = iter(items)
@@ -307,6 +324,18 @@ class InlineKeyboardBuilder(KeyboardBuilder[InlineKeyboardButton]):
         """
         return InlineKeyboardBuilder(markup=self.export())
 
+    @classmethod
+    def from_markup(
+        cls: Type["InlineKeyboardBuilder"], markup: InlineKeyboardMarkup
+    ) -> "InlineKeyboardBuilder":
+        """
+        Create builder from existing markup
+
+        :param markup:
+        :return:
+        """
+        return cls(markup=markup.inline_keyboard)
+
 
 class ReplyKeyboardBuilder(KeyboardBuilder[KeyboardButton]):
     """
@@ -340,3 +369,13 @@ class ReplyKeyboardBuilder(KeyboardBuilder[KeyboardButton]):
         :return:
         """
         return ReplyKeyboardBuilder(markup=self.export())
+
+    @classmethod
+    def from_markup(cls, markup: ReplyKeyboardMarkup) -> "ReplyKeyboardBuilder":
+        """
+        Create builder from existing markup
+
+        :param markup:
+        :return:
+        """
+        return cls(markup=markup.keyboard)