docs: add docstrings to PageMenu

CHANGELOG.md

@@ -29,6 +29,7 @@
    - Add docstrings to `Keyboard` ([c3b4f5f879eec2d953ed47be26e03241a7b0cfe7](https://github.com/hearot/pyrubrum/commit/c3b4f5f879eec2d953ed47be26e03241a7b0cfe7))
    - Add docstrings to `Menu` ([15c11e4f737c0c63bad29d6c3c758d2b775c9ea4](https://github.com/hearot/pyrubrum/commit/15c11e4f737c0c63bad29d6c3c758d2b775c9ea4))
    - Add docstrings to `Node` ([caf69bb8f7c6542bb731b7df6bf0f7ab7b3d4bd9](https://github.com/hearot/pyrubrum/commit/caf69bb8f7c6542bb731b7df6bf0f7ab7b3d4bd9))
+   - Add docstrings to `PageMenu`
    - Add docstrings to `ParameterizedBaseHandler` ([579ad0916dc138c0d3117ae6f90e92a1cf11c1ea](https://github.com/hearot/pyrubrum/commit/579ad0916dc138c0d3117ae6f90e92a1cf11c1ea))
    - Add docstrings to `ParameterizedHandler` ([9b3e293e2e1a63fa79c557ca496a22facf36c76b](https://github.com/hearot/pyrubrum/commit/9b3e293e2e1a63fa79c557ca496a22facf36c76b))
    - Add docstrings to `RedisDatabase` ([784b8f112d561b9a346b7f986710df2b1455e691](https://github.com/hearot/pyrubrum/commit/784b8f112d561b9a346b7f986710df2b1455e691))
@@ -38,7 +39,7 @@
    - Add the official pronunciation for Pyrubrum ([b6d1fe8e01f79007338cd4a6dfe409c406c12cba](https://github.com/hearot/pyrubrum/commit/b6d1fe8e01f79007338cd4a6dfe409c406c12cba))
    - Create the changelog of the current release separately ([318172a986e666ac4abf6f7a4480922cb135e734](https://github.com/hearot/pyrubrum/commit/318172a986e666ac4abf6f7a4480922cb135e734))
    - Delete duplicate issue templates ([10cba65c31a5c3556b39cc328d097b62dfbd5e1b](https://github.com/hearot/pyrubrum/commit/10cba65c31a5c3556b39cc328d097b62dfbd5e1b))
-   - Extend the definition of `ParameterizedBaseHandler`
+   - Extend the definition of `ParameterizedBaseHandler` ([08b258866b4182afae6fc7e439a74b5e30d86f4e](https://github.com/hearot/pyrubrum/commit/08b258866b4182afae6fc7e439a74b5e30d86f4e))
    - Make relative clauses more formal ([6b0d84effd65838668b3ba070a677d03ce016581](https://github.com/hearot/pyrubrum/commit/6b0d84effd65838668b3ba070a677d03ce016581))
    - Stop using `typing.NewType` and use aliases instead ([600191f337178baf21ea5ffe3e9caaa19dbf22e0](https://github.com/hearot/pyrubrum/commit/600191f337178baf21ea5ffe3e9caaa19dbf22e0))
    - Update the disclaimer notices ([b5039179f28a24ecf967b66200c9440cb6b6c6ec](https://github.com/hearot/pyrubrum/commit/b5039179f28a24ecf967b66200c9440cb6b6c6ec))

FEATURES.md

@@ -15,6 +15,7 @@
    - Add docstrings to `Keyboard` ([c3b4f5f879eec2d953ed47be26e03241a7b0cfe7](https://github.com/hearot/pyrubrum/commit/c3b4f5f879eec2d953ed47be26e03241a7b0cfe7))
    - Add docstrings to `Menu` ([15c11e4f737c0c63bad29d6c3c758d2b775c9ea4](https://github.com/hearot/pyrubrum/commit/15c11e4f737c0c63bad29d6c3c758d2b775c9ea4))
    - Add docstrings to `Node` ([caf69bb8f7c6542bb731b7df6bf0f7ab7b3d4bd9](https://github.com/hearot/pyrubrum/commit/caf69bb8f7c6542bb731b7df6bf0f7ab7b3d4bd9))
+   - Add docstrings to `PageMenu`
    - Add docstrings to `ParameterizedBaseHandler` ([579ad0916dc138c0d3117ae6f90e92a1cf11c1ea](https://github.com/hearot/pyrubrum/commit/579ad0916dc138c0d3117ae6f90e92a1cf11c1ea))
    - Add docstrings to `ParameterizedHandler` ([9b3e293e2e1a63fa79c557ca496a22facf36c76b](https://github.com/hearot/pyrubrum/commit/9b3e293e2e1a63fa79c557ca496a22facf36c76b))
    - Add docstrings to `RedisDatabase` ([784b8f112d561b9a346b7f986710df2b1455e691](https://github.com/hearot/pyrubrum/commit/784b8f112d561b9a346b7f986710df2b1455e691))
@@ -24,7 +25,7 @@
    - Add the official pronunciation for Pyrubrum ([b6d1fe8e01f79007338cd4a6dfe409c406c12cba](https://github.com/hearot/pyrubrum/commit/b6d1fe8e01f79007338cd4a6dfe409c406c12cba))
    - Create the changelog of the current release separately ([318172a986e666ac4abf6f7a4480922cb135e734](https://github.com/hearot/pyrubrum/commit/318172a986e666ac4abf6f7a4480922cb135e734))
    - Delete duplicate issue templates ([10cba65c31a5c3556b39cc328d097b62dfbd5e1b](https://github.com/hearot/pyrubrum/commit/10cba65c31a5c3556b39cc328d097b62dfbd5e1b))
-   - Extend the definition of `ParameterizedBaseHandler`
+   - Extend the definition of `ParameterizedBaseHandler` ([08b258866b4182afae6fc7e439a74b5e30d86f4e](https://github.com/hearot/pyrubrum/commit/08b258866b4182afae6fc7e439a74b5e30d86f4e))
    - Make relative clauses more formal ([6b0d84effd65838668b3ba070a677d03ce016581](https://github.com/hearot/pyrubrum/commit/6b0d84effd65838668b3ba070a677d03ce016581))
    - Stop using `typing.NewType` and use aliases instead ([600191f337178baf21ea5ffe3e9caaa19dbf22e0](https://github.com/hearot/pyrubrum/commit/600191f337178baf21ea5ffe3e9caaa19dbf22e0))
    - Update the disclaimer notices ([b5039179f28a24ecf967b66200c9440cb6b6c6ec](https://github.com/hearot/pyrubrum/commit/b5039179f28a24ecf967b66200c9440cb6b6c6ec))

pyrubrum/page_menu.py

@@ -37,21 +37,46 @@
 from .menu import Menu
 from .parameterized_handler import ParameterizedHandler
 
+Items = Union[
+    List[Element],
+    Callable[
+        [
+            ParameterizedHandler,
+            Client,
+            Union[CallbackQuery, Message],
+            Dict[str, Any],
+        ],
+        List[Element],
+    ],
+]
+
 
 @dataclass(eq=False, init=False, repr=True)
 class PageMenu(Menu):
-    items: Union[
-        List[Element],
-        Callable[
-            [
-                ParameterizedHandler,
-                Client,
-                Union[CallbackQuery, Message],
-                Dict[str, Any],
-            ],
-            List[Element],
-        ],
-    ]
+    """Implementation of a menu which automatically, given a list of items, manages
+    paging and the setting of parameters. It has got, by definition, a list of
+    items, which can be provided using a custom function as well, a limit of
+    displayed elements per page and custom texts for the buttons which let the
+    user change the displayed page.
+
+    Attributes:
+        items (Items): The list of elements the menu is compounded of or a
+            function which returns such type of value.
+        limit_page (Optional[int]): The limit of elements per page. Defaults to
+            4.
+        next_page_button_text (Optional[str]): The text which is displayed
+            inside the button that lets the user move on to the next page, if
+            any. Defaults to "▶️".
+        previous_page_button_text (Optional[str]): The text which is displayed
+            inside the button that lets the user go back to the previous page,
+            if any. Defaults to "◀️".
+
+    Warning:
+        This implementation is not compatible with a non parameterized handler.
+        An handler that supports parameterization is required.
+    """
+
+    items: Items
     limit_page: Optional[int] = 4
     next_page_button_text: Optional[str] = "▶️"
     previous_page_button_text: Optional[str] = "◀️"
@@ -61,24 +86,45 @@ def __init__(
         name: str,
         menu_id: str,
         content: Union[InputMedia, str],
-        items: Union[
-            List[Element],
-            Callable[
-                [
-                    ParameterizedHandler,
-                    Client,
-                    Union[CallbackQuery, Message],
-                    Dict[str, Any],
-                ],
-                List[Element],
-            ],
-        ],
+        items: Items,
         back_button_text: Optional[str] = "🔙",
         limit: Optional[int] = 2,
         limit_page: Optional[int] = 4,
         next_page_button_text: Optional[str] = "▶️",
         previous_page_button_text: Optional[str] = "◀️",
     ):
+        """Initialize the object.
+
+        Args:
+            name (str): The name you give to the menu, which will be used as
+                the text of callback button, if needed. See `BaseMenu` for more
+                information.
+            menu_id (str): The unique identifier given to the menu, which will
+                refer unequivocally to this entity. The hash for this class is
+                generated relying on the content of this field. See `BaseMenu`
+                for more information.
+            content (Content): What will be displayed whenever a user accesses
+                this menu. Both text and media can be provided. A function can
+                be provided as well and must follow the following arguments
+                pattern:
+                    ``func(handler, client, context, parameters)``
+                See `Menu` for more information.
+            items (Items): The list of elements the menu is compounded of or a
+                function which returns such type of value.
+            back_button_text (Optional[str]): The text which will be displayed
+                inside the button that lets the user go back to the parent
+                menu. Defaults to "🔙". See `Menu` for more information.
+            limit (Optional[int]): The limit of buttons per row. Defaults to 2.
+                See `Menu` for more information.
+            limit_page (Optional[int]): The limit of elements per page.
+                Defaults to 4.
+            next_page_button_text (Optional[str]): The text which is displayed
+                inside the button that lets the user move on to the next page,
+                if any. Defaults to "▶️".
+            previous_page_button_text (Optional[str]): The text which is
+                displayed inside the button that lets the user go back to the
+                previous page, if any. Defaults to "◀️".
+        """
         Menu.__init__(
             self,
             name,
@@ -100,6 +146,44 @@ def keyboard(
         context: Union[CallbackQuery, Message],
         parameters: Dict[str, Any],
     ) -> InlineKeyboardMarkup:
+        """Provide a keyboard which is created relying on the page provided by the
+        parameters and is built following the limits defined during the
+        initialization of this instance (i.e. `limit` and `limit_page`).
+
+        The page is retrieved from the parameters relying on the page
+        identifier, which is built in the following way:
+            ``page_[MENU_ID]``
+
+        Hence, there is a special set of keys for parameters that is
+        recommended not to be used in order to handle paging in a proper way.
+        All keys starting with ``page_`` shall then be avoided.
+
+        If this menu has been referenced by this menu itself (i.e. the user
+        clicked on the buttons for moving between pages), the page is set to be
+        equal to ``element_id``, which represents the page itself.
+
+        As a result of this, during the build of the the teleport buttons (i.e.
+        the buttons for moving between pages) the ``element_id`` is set to be
+        equal to the page the buttons refer to (e.g. page plus one for "Go to
+        the next page").
+
+        In the end, the keyboard is filled with all the buttons which refer to
+        the menus that are linked to the children of this menu node and a
+        special button for linking the user to the parent menu, if any.
+
+        Args:
+            handler (ParameterizedHandler): The handler which coordinates the
+                management of the menus and supports parameterization.
+            client (Client): The client which is linked to the handler.
+            context (Union[CallbackQuery, Message]): The context for which the
+                button is generated.
+            parameters (Dict[str, Any]): The parameters which were passed to
+                the handler.
+
+        Returns:
+            InlineKeyboardMarkup: The generated inline keyboard, which is then
+                displayed to the user.
+        """
         parent, children = tree.get_family(self.menu_id)
 
         keyboard = []