Documentation Improvements (#4109, #4116)

Co-authored-by: Aditya <adityayadav11082@gmail.com>
Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>
Co-authored-by: Maurice Banerjee Palmer <31225563+mbanerjeepalmer@users.noreply.github.com>

README.rst

@@ -46,10 +46,6 @@
    :target: https://app.codacy.com/gh/python-telegram-bot/python-telegram-bot/dashboard
    :alt: Code quality: Codacy
 
-.. image:: https://app.deepsource.com/gh/python-telegram-bot/python-telegram-bot.svg/?label=active+issues
-   :target: https://app.deepsource.com/gh/python-telegram-bot/python-telegram-bot/?ref=repository-badge
-   :alt: Code quality: DeepSource
-
 .. image:: https://results.pre-commit.ci/badge/github/python-telegram-bot/python-telegram-bot/master.svg
    :target: https://results.pre-commit.ci/latest/github/python-telegram-bot/python-telegram-bot/master
    :alt: pre-commit.ci status

README_RAW.rst

@@ -46,10 +46,6 @@
    :target: https://app.codacy.com/gh/python-telegram-bot/python-telegram-bot/dashboard
    :alt: Code quality: Codacy
 
-.. image:: https://app.deepsource.com/gh/python-telegram-bot/python-telegram-bot.svg/?label=active+issues
-   :target: https://app.deepsource.com/gh/python-telegram-bot/python-telegram-bot/?ref=repository-badge
-   :alt: Code quality: DeepSource
-
 .. image:: https://results.pre-commit.ci/badge/github/python-telegram-bot/python-telegram-bot/master.svg
    :target: https://results.pre-commit.ci/latest/github/python-telegram-bot/python-telegram-bot/master
    :alt: pre-commit.ci status

docs/requirements-docs.txt

@@ -1,6 +1,6 @@
 sphinx==7.2.6
 furo==2024.1.29
-git+https://github.com/harshil21/furo-sphinx-search@v0.2.0.1
+furo-sphinx-search @ git+https://github.com/harshil21/furo-sphinx-search@v0.2.0.1
 sphinx-paramlinks==0.6.0
 sphinxcontrib-mermaid==0.9.2
 sphinx-copybutton==0.5.2

docs/source/telegram.constants.rst

@@ -4,4 +4,6 @@ telegram.constants Module
 .. automodule:: telegram.constants
     :members:
     :show-inheritance:
-    :inherited-members: Enum, EnumMeta
+    :no-undoc-members:
+    :inherited-members: Enum, EnumMeta, str, int
+    :exclude-members: __format__, __new__, __repr__, __str__

examples/deeplinking.py

@@ -20,7 +20,13 @@
 
 import logging
 
-from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update, helpers
+from telegram import (
+    InlineKeyboardButton,
+    InlineKeyboardMarkup,
+    LinkPreviewOptions,
+    Update,
+    helpers,
+)
 from telegram.constants import ParseMode
 from telegram.ext import Application, CallbackQueryHandler, CommandHandler, ContextTypes, filters
 
@@ -70,7 +76,9 @@ async def deep_linked_level_2(update: Update, context: ContextTypes.DEFAULT_TYPE
     bot = context.bot
     url = helpers.create_deep_linked_url(bot.username, USING_ENTITIES)
     text = f'You can also mask the deep-linked URLs as links: <a href="{url}">▶️ CLICK HERE</a>.'
-    await update.message.reply_text(text, parse_mode=ParseMode.HTML, disable_web_page_preview=True)
+    await update.message.reply_text(
+        text, parse_mode=ParseMode.HTML, link_preview_options=LinkPreviewOptions(is_disabled=True)
+    )
 
 
 async def deep_linked_level_3(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:

telegram/_bot.py

@@ -1110,10 +1110,11 @@ async def delete_messages(
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
-            message_ids (Sequence[:obj:`int`]): Identifiers of
+            message_ids (Sequence[:obj:`int`]): A list of
                 :tg-const:`telegram.constants.BulkRequestLimit.MIN_LIMIT`-
-                :tg-const:`telegram.constants.BulkRequestLimit.MAX_LIMIT` messages to delete.
-                See :meth:`delete_message` for limitations on which messages can be deleted.
+                :tg-const:`telegram.constants.BulkRequestLimit.MAX_LIMIT` identifiers of messages
+                to delete. See :meth:`delete_message` for limitations on which messages can be
+                deleted.
 
         Returns:
             :obj:`bool`: On success, :obj:`True` is returned.
@@ -1225,11 +1226,11 @@ async def forward_messages(
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
             from_chat_id (:obj:`int` | :obj:`str`): Unique identifier for the chat where the
                 original message was sent (or channel username in the format ``@channelusername``).
-            message_ids (Sequence[:obj:`int`]): Identifiers of
+            message_ids (Sequence[:obj:`int`]): A list of
                 :tg-const:`telegram.constants.BulkRequestLimit.MIN_LIMIT`-
-                :tg-const:`telegram.constants.BulkRequestLimit.MAX_LIMIT` messages in the chat
-                :paramref:`from_chat_id` to forward. The identifiers must be specified in a
-                strictly increasing order.
+                :tg-const:`telegram.constants.BulkRequestLimit.MAX_LIMIT` identifiers of messages
+                in the chat :paramref:`from_chat_id` to forward. The identifiers must be specified
+                in a strictly increasing order.
             disable_notification (:obj:`bool`, optional): |disable_notification|
             protect_content (:obj:`bool`, optional): |protect_content|
             message_thread_id (:obj:`int`, optional): |message_thread_id_arg|
@@ -4127,10 +4128,11 @@ async def get_updates(
                 "edited_channel_post", "callback_query"] to only receive updates of these types.
                 See :class:`telegram.Update` for a complete list of available update types.
                 Specify an empty sequence to receive all updates except
-                :attr:`telegram.Update.chat_member` (default). If not specified, the previous
-                setting will be used. Please note that this parameter doesn't affect updates
-                created before the call to the get_updates, so unwanted updates may be received for
-                a short period of time.
+                :attr:`telegram.Update.chat_member`, :attr:`telegram.Update.message_reaction` and
+                :attr:`telegram.Update.message_reaction_count` (default). If not specified, the
+                previous setting will be used. Please note that this parameter doesn't affect
+                updates created before the call to the get_updates, so unwanted updates may be
+                received for a short period of time.
 
                 .. versionchanged:: 20.0
                     |sequenceargs|
@@ -4268,10 +4270,13 @@ async def set_webhook(
                 "edited_channel_post", "callback_query"] to only receive updates of these types.
                 See :class:`telegram.Update` for a complete list of available update types.
                 Specify an empty sequence to receive all updates except
-                :attr:`telegram.Update.chat_member` (default). If not specified, the previous
-                setting will be used. Please note that this parameter doesn't affect updates
-                created before the call to the set_webhook, so unwanted updates may be received for
-                a short period of time.
+                :attr:`telegram.Update.chat_member`,
+                :attr:`telegram.Update.message_reaction`
+                and :attr:`telegram.Update.message_reaction_count` (default). If not
+                specified, the previous setting will be used. Please note that this
+                parameter doesn't affect
+                updates created before the call to the set_webhook, so unwanted update
+                may be received for a short period of time.
 
                 .. versionchanged:: 20.0
                     |sequenceargs|
@@ -5265,23 +5270,23 @@ async def promote_chat_member(
             can_change_info (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
                 change chat title, photo and other settings.
             can_post_messages (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
-                post messages in the channel, or access channel statistics; channels only.
+                post messages in the channel, or access channel statistics; for channels only.
             can_edit_messages (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
-                edit messages of other users and can pin messages, channels only.
+                edit messages of other users and can pin messages, for channels only.
             can_delete_messages (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
                 delete messages of other users.
             can_invite_users (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
                 invite new users to the chat.
             can_restrict_members (:obj:`bool`, optional): Pass :obj:`True`, if the administrator
                 can restrict, ban or unban chat members, or access supergroup statistics.
             can_pin_messages (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
-                pin messages, supergroups only.
+                pin messages, for supergroups only.
             can_promote_members (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
                 add new administrators with a subset of their own privileges or demote
                 administrators that they have promoted, directly or indirectly
                 (promoted by administrators that were appointed by the user).
             can_manage_topics (:obj:`bool`, optional): Pass :obj:`True`, if the user is
-                allowed to create, rename, close, and reopen forum topics; supergroups only.
+                allowed to create, rename, close, and reopen forum topics; for supergroups only.
 
                 .. versionadded:: 20.0
             can_post_stories (:obj:`bool`, optional): Pass :obj:`True`, if the administrator can
@@ -7577,11 +7582,11 @@ async def copy_messages(
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
             from_chat_id (:obj:`int` | :obj:`str`): Unique identifier for the chat where the
                 original message was sent (or channel username in the format ``@channelusername``).
-            message_ids (Sequence[:obj:`int`]): Identifiers of
+            message_ids (Sequence[:obj:`int`]): A list of
                 :tg-const:`telegram.constants.BulkRequestLimit.MIN_LIMIT` -
-                :tg-const:`telegram.constants.BulkRequestLimit.MAX_LIMIT` messages in the chat.
-                :paramref:`from_chat_id` to copy. The identifiers must be specified in a strictly
-                increasing order.
+                :tg-const:`telegram.constants.BulkRequestLimit.MAX_LIMIT` identifiers of messages
+                in the chat :paramref:`from_chat_id` to copy. The identifiers must be
+                specified in a strictly increasing order.
             disable_notification (:obj:`bool`, optional): |disable_notification|
             protect_content (:obj:`bool`, optional): |protect_content|
             message_thread_id (:obj:`int`, optional): |message_thread_id_arg|
@@ -8731,7 +8736,7 @@ async def set_message_reaction(
                 media group, the reaction is set to the first non-deleted message in the group
                 instead.
             reaction (Sequence[:class:`telegram.ReactionType` | :obj:`str`] | \
-                :class:`telegram.ReactionType` | :obj:`str`, optional): New list of reaction
+                :class:`telegram.ReactionType` | :obj:`str`, optional): A list of reaction
                 types to set on the message. Currently, as non-premium users, bots can set up to
                 one reaction per message. A custom emoji reaction can be used if it is either
                 already present on the message or explicitly allowed by chat administrators.

telegram/_chat.py

@@ -2583,7 +2583,7 @@ async def copy_message(
         .. seealso:: :meth:`send_copy`, :meth:`send_copies`, :meth:`copy_messages`.
 
         Returns:
-            :class:`telegram.Message`: On success, instance representing the message posted.
+            :class:`telegram.MessageId`: On success, returns the MessageId of the sent message.
 
         """
         return await self.get_bot().copy_message(

telegram/_chatadministratorrights.py

@@ -60,15 +60,15 @@ class ChatAdministratorRights(TelegramObject):
             that they have promoted, directly or indirectly (promoted by administrators that
             were appointed by the user).
         can_change_info (:obj:`bool`): :obj:`True`, if the user is allowed to change the chat title
-            ,photo and other settings.
+            , photo and other settings.
         can_invite_users (:obj:`bool`): :obj:`True`, if the user is allowed to invite new users to
             the chat.
         can_post_messages (:obj:`bool`, optional): :obj:`True`, if the administrator can post
-            messages in the channel, or access channel statistics; channels only.
+            messages in the channel, or access channel statistics; for channels only.
         can_edit_messages (:obj:`bool`, optional): :obj:`True`, if the administrator can edit
-            messages of other users.
+            messages of other users and can pin messages; for channels only.
         can_pin_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed to pin
-            messages; groups and supergroups only.
+            messages; for groups and supergroups only.
         can_post_stories (:obj:`bool`): :obj:`True`, if the administrator can post
             stories to the chat.
 
@@ -88,7 +88,7 @@ class ChatAdministratorRights(TelegramObject):
             .. versionchanged:: NEXT.VERSION
                 |non_optional_story_argument|
         can_manage_topics (:obj:`bool`, optional): :obj:`True`, if the user is allowed
-            to create, rename, close, and reopen forum topics; supergroups only.
+            to create, rename, close, and reopen forum topics; for supergroups only.
 
             .. versionadded:: 20.0
 
@@ -112,11 +112,11 @@ class ChatAdministratorRights(TelegramObject):
         can_invite_users (:obj:`bool`): :obj:`True`, if the user is allowed to invite new users to
             the chat.
         can_post_messages (:obj:`bool`): Optional. :obj:`True`, if the administrator can post
-            messages in the channel, or access channel statistics; channels only.
+            messages in the channel, or access channel statistics; for channels only.
         can_edit_messages (:obj:`bool`): Optional. :obj:`True`, if the administrator can edit
-            messages of other users.
+            messages of other users and can pin messages; for channels only.
         can_pin_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to pin
-            messages; groups and supergroups only.
+            messages; for groups and supergroups only.
         can_post_stories (:obj:`bool`): :obj:`True`, if the administrator can post
             stories to the chat.
 
@@ -136,7 +136,7 @@ class ChatAdministratorRights(TelegramObject):
             .. versionchanged:: NEXT.VERSION
                 |non_optional_story_argument|
         can_manage_topics (:obj:`bool`): Optional. :obj:`True`, if the user is allowed
-            to create, rename, close, and reopen forum topics; supergroups only.
+            to create, rename, close, and reopen forum topics; for supergroups only.
 
             .. versionadded:: 20.0
     """

telegram/_chatmember.py

@@ -217,13 +217,13 @@ class ChatMemberAdministrator(ChatMember):
         can_invite_users (:obj:`bool`): :obj:`True`, if the user can invite
             new users to the chat.
         can_post_messages (:obj:`bool`, optional): :obj:`True`, if the
-            administrator can post messages in the channel, or access channel statistics; channels
-            only.
+            administrator can post messages in the channel, or access channel statistics;
+            for channels only.
         can_edit_messages (:obj:`bool`, optional): :obj:`True`, if the
             administrator can edit messages of other users and can pin
-            messages; channels only.
+            messages; for channels only.
         can_pin_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed
-            to pin messages; groups and supergroups only.
+            to pin messages; for groups and supergroups only.
         can_post_stories (:obj:`bool`): :obj:`True`, if the administrator can post
             stories to the chat.
 
@@ -243,7 +243,7 @@ class ChatMemberAdministrator(ChatMember):
             .. versionchanged:: NEXT.VERSION
                 |non_optional_story_argument|
         can_manage_topics (:obj:`bool`, optional): :obj:`True`, if the user is allowed
-            to create, rename, close, and reopen forum topics; supergroups only.
+            to create, rename, close, and reopen forum topics; for supergroups only.
 
             .. versionadded:: 20.0
         custom_title (:obj:`str`, optional): Custom title for this user.
@@ -277,12 +277,12 @@ class ChatMemberAdministrator(ChatMember):
             new users to the chat.
         can_post_messages (:obj:`bool`): Optional. :obj:`True`, if the
             administrator can post messages in the channel or access channel statistics;
-            channels only.
+            for channels only.
         can_edit_messages (:obj:`bool`): Optional. :obj:`True`, if the
             administrator can edit messages of other users and can pin
-            messages; channels only.
+            messages; for channels only.
         can_pin_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed
-            to pin messages; groups and supergroups only.
+            to pin messages; for groups and supergroups only.
         can_post_stories (:obj:`bool`): :obj:`True`, if the administrator can post
             stories to the chat.
 
@@ -302,7 +302,7 @@ class ChatMemberAdministrator(ChatMember):
             .. versionchanged:: NEXT.VERSION
                 |non_optional_story_argument|
         can_manage_topics (:obj:`bool`): Optional. :obj:`True`, if the user is allowed
-            to create, rename, close, and reopen forum topics; supergroups only
+            to create, rename, close, and reopen forum topics; for supergroups only
 
             .. versionadded:: 20.0
         custom_title (:obj:`str`): Optional. Custom title for this user.