From 28052a6cc1f8197ad26747753f60eec4ccf5df48 Mon Sep 17 00:00:00 2001
From: JRoot Junior <jroot.junior@gmail.com>
Date: Mon, 27 May 2024 14:39:41 +0300
Subject: [PATCH] Added docs and changelog

---
 CHANGES/1494.removal.rst |  2 +
 aiogram/client/bot.py    |  2 +-
 docs/api/defaults.rst    | 81 ++++++++++++++++++++++++++++++++++++++++
 docs/api/index.rst       |  1 +
 4 files changed, 85 insertions(+), 1 deletion(-)
 create mode 100644 CHANGES/1494.removal.rst
 create mode 100644 docs/api/defaults.rst

diff --git a/CHANGES/1494.removal.rst b/CHANGES/1494.removal.rst
new file mode 100644
index 00000000..935d2f0a
--- /dev/null
+++ b/CHANGES/1494.removal.rst
@@ -0,0 +1,2 @@
+Removed deprecated arguments from Bot class
+:code:`parse_mode`, :code:`disable_web_page_preview`, :code:`protect_content` as previously announced in v3.4.0.
diff --git a/aiogram/client/bot.py b/aiogram/client/bot.py
index 572d75d8..94ffa3dc 100644
--- a/aiogram/client/bot.py
+++ b/aiogram/client/bot.py
@@ -295,7 +295,7 @@ class Bot:
             raise TypeError(
                 "Passing `parse_mode`, `disable_web_page_preview` or `protect_content` "
                 "to Bot initializer is not supported anymore. These arguments have been removed "
-                f"in 3.7.0 version. Use `default=DefaultBotProperties({replacement_spec})` instead."
+                f"in 3.7.0 version. Use `default=DefaultBotProperties({replacement_spec})` argument instead."
             )
 
         self.default = default
diff --git a/docs/api/defaults.rst b/docs/api/defaults.rst
new file mode 100644
index 00000000..93f3a59b
--- /dev/null
+++ b/docs/api/defaults.rst
@@ -0,0 +1,81 @@
+===============
+Global defaults
+===============
+
+aiogram provides mechanism to set some global defaults for all requests to Telegram Bot API
+in your application using :class:`aiogram.client.default.DefaultBotProperties` class.
+
+There are some properties that can be set:
+
+.. autoclass:: aiogram.client.default.DefaultBotProperties
+    :members:
+    :member-order: bysource
+    :undoc-members: True
+
+.. note::
+
+    If you need to override default properties for some requests, you should use `aiogram.client.default.DefaultBotProperties`
+    only for properties that you want to set as defaults and pass explicit values for other properties.
+
+.. danger::
+
+    If you upgrading from aiogram 3.0-3.6 to 3.7,
+    you should update your code to use `aiogram.client.default.DefaultBotProperties`.
+
+Example
+=======
+
+Here is an example of setting default parse mode for all requests to Telegram Bot API:
+
+.. code-block:: python
+
+    bot = Bot(
+        token=...,
+        defaults=DefaultBotProperties(
+            parse_mode=ParseMode.HTML,
+        )
+    )
+
+In this case all messages sent by this bot will be parsed as HTML, so you don't need to specify `parse_mode`
+in every message you send.
+
+Instead of
+
+.. code-block:: python
+
+    await bot.send_message(chat_id, text, parse_mode=ParseMode.HTML)
+
+you can use
+
+.. code-block:: python
+
+    await bot.send_message(chat_id, text)
+
+and the message will be sent with HTML parse mode.
+
+In some cases you may want to override default properties for some requests. You can do it by passing
+explicit values to the method:
+
+.. code-block:: python
+
+    await bot.send_message(chat_id, text, parse_mode=ParseMode.MARKDOWN_V2)
+
+In this case the message will be sent with Markdown parse mode instead of default HTML.
+
+Another example of overriding default properties:
+
+.. code-block:: python
+
+    await bot.send_message(chat_id, text, parse_mode=None)
+
+In this case the message will be send withoout parse mode, even if default parse mode is set it may be useful
+if you want to send message with plain text or :ref:`aiogram.types.message_entity.MessageEntity`.
+
+.. code-block:: python
+
+    await bot.send_message(
+        chat_id=chat_id,
+        text=text,
+        entities=[MessageEntity(type='bold', offset=0, length=4)],
+        parse_mode=None
+    )
diff --git a/docs/api/index.rst b/docs/api/index.rst
index d323ecf0..89a35839 100644
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -14,3 +14,4 @@ All methods and types is fully autogenerated from Telegram Bot API docs by parse
     enums/index
     download_file
     upload_file
+    defaults