Documentation Improvements (#3370, #3376, #3366)

Co-authored-by: Viicos <65306057+Viicos@users.noreply.github.com>

docs/substitutions/global.rst

@@ -26,7 +26,7 @@
 
 .. |chat_id_group| replace:: Unique identifier for the target chat or username of the target supergroup (in the format ``@supergroupusername``).
 
-.. |parse_mode| replace:: Send Markdown or HTML, if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your bot's message. See the constants in :class:`telegram.constants.ParseMode` for the available modes.
+.. |parse_mode| replace:: Mode for parsing entities. See :class:`telegram.constants.ParseMode` and `formatting options <https://core.telegram.org/bots/api#formatting-options>`__ for more details.
 
 .. |allow_sending_without_reply| replace:: Pass :obj:`True`, if the message should be sent even if the specified replied-to message is not found.
 

telegram/_files/inputmedia.py

@@ -55,12 +55,8 @@ class InputMedia(TelegramObject):
         caption (:obj:`str`, optional): Caption of the media to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            entities that appear in the caption, which can be specified instead of
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            :paramref:`parse_mode`.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
 
     Attributes:
         type (:obj:`str`): Type of the input media.
@@ -127,12 +123,8 @@ class InputMediaAnimation(InputMedia):
         caption (:obj:`str`, optional): Caption of the animation to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         width (:obj:`int`, optional): Animation width.
         height (:obj:`int`, optional): Animation height.
         duration (:obj:`int`, optional): Animation duration in seconds.
@@ -209,12 +201,8 @@ class InputMediaPhoto(InputMedia):
         caption (:obj:`str`, optional ): Caption of the photo to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InputMediaType.PHOTO`.
@@ -277,12 +265,8 @@ class InputMediaVideo(InputMedia):
         caption (:obj:`str`, optional): Caption of the video to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         width (:obj:`int`, optional): Video width.
         height (:obj:`int`, optional): Video height.
         duration (:obj:`int`, optional): Video duration in seconds.
@@ -376,12 +360,8 @@ class InputMediaAudio(InputMedia):
         caption (:obj:`str`, optional): Caption of the audio to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         duration (:obj:`int`): Duration of the audio in seconds as defined by sender.
         performer (:obj:`str`, optional): Performer of the audio as defined by sender or by audio
             tags.
@@ -465,12 +445,8 @@ class InputMediaDocument(InputMedia):
         caption (:obj:`str`, optional): Caption of the document to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         thumb (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | :obj:`str`, \
                 optional): |thumbdocstringnopath|
 

telegram/_inline/inlinequery.py

@@ -72,7 +72,7 @@ class InlineQuery(TelegramObject):
         offset (:obj:`str`): Offset of the results to be returned, can be controlled by the bot.
         location (:class:`telegram.Location`): Optional. Sender location, only for bots that
             request user location.
-        chat_type (:obj:`str`, optional): Type of the chat, from which the inline query was sent.
+        chat_type (:obj:`str`): Optional. Type of the chat, from which the inline query was sent.
 
             .. versionadded:: 13.5
 

telegram/_inline/inlinequeryresultaudio.py

@@ -46,12 +46,8 @@ class InlineQueryResultAudio(InlineQueryResult):
         caption (:obj:`str`, optional): Caption,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -67,12 +63,8 @@ class InlineQueryResultAudio(InlineQueryResult):
         caption (:obj:`str`): Optional. Caption,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`): Optional. |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

telegram/_inline/inlinequeryresultcachedaudio.py

@@ -43,12 +43,8 @@ class InlineQueryResultCachedAudio(InlineQueryResult):
         caption (:obj:`str`, optional): Caption,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -61,12 +57,8 @@ class InlineQueryResultCachedAudio(InlineQueryResult):
         caption (:obj:`str`): Optional. Caption,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optionals): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

telegram/_inline/inlinequeryresultcacheddocument.py

@@ -45,12 +45,8 @@ class InlineQueryResultCachedDocument(InlineQueryResult):
         caption (:obj:`str`, optional): Caption of the document to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -65,12 +61,8 @@ class InlineQueryResultCachedDocument(InlineQueryResult):
         caption (:obj:`str`): Optional. Caption of the document to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`): Optional. |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

telegram/_inline/inlinequeryresultcachedgif.py

@@ -45,12 +45,8 @@ class InlineQueryResultCachedGif(InlineQueryResult):
         caption (:obj:`str`, optional): Caption of the GIF file to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -64,12 +60,8 @@ class InlineQueryResultCachedGif(InlineQueryResult):
         caption (:obj:`str`): Optional. Caption of the GIF file to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`): Optional. |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

telegram/_inline/inlinequeryresultcachedmpeg4gif.py

@@ -45,12 +45,8 @@ class InlineQueryResultCachedMpeg4Gif(InlineQueryResult):
         caption (:obj:`str`, optional): Caption of the MPEG-4 file to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -64,12 +60,8 @@ class InlineQueryResultCachedMpeg4Gif(InlineQueryResult):
         caption (:obj:`str`): Optional. Caption of the MPEG-4 file to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`): Optional. |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

telegram/_inline/inlinequeryresultcachedphoto.py

@@ -46,12 +46,8 @@ class InlineQueryResultCachedPhoto(InlineQueryResult):
         caption (:obj:`str`, optional): Caption of the photo to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -66,12 +62,8 @@ class InlineQueryResultCachedPhoto(InlineQueryResult):
         caption (:obj:`str`): Optional. Caption of the photo to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`): Optional. |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

telegram/_inline/inlinequeryresultcachedvideo.py

@@ -46,12 +46,8 @@ class InlineQueryResultCachedVideo(InlineQueryResult):
         caption (:obj:`str`, optional): Caption of the video to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -66,12 +62,8 @@ class InlineQueryResultCachedVideo(InlineQueryResult):
         caption (:obj:`str`): Optional. Caption of the video to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`): Optional. |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

telegram/_inline/inlinequeryresultcachedvoice.py

@@ -44,12 +44,8 @@ class InlineQueryResultCachedVoice(InlineQueryResult):
         caption (:obj:`str`, optional): Caption,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -63,12 +59,8 @@ class InlineQueryResultCachedVoice(InlineQueryResult):
         caption (:obj:`str`): Optional. Caption,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`): Optional. |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

telegram/_inline/inlinequeryresultdocument.py

@@ -44,12 +44,8 @@ class InlineQueryResultDocument(InlineQueryResult):
         caption (:obj:`str`, optional): Caption of the document to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         document_url (:obj:`str`): A valid URL for the file.
         mime_type (:obj:`str`): Mime type of the content of the file, either "application/pdf"
             or "application/zip".
@@ -69,12 +65,8 @@ class InlineQueryResultDocument(InlineQueryResult):
         caption (:obj:`str`): Optional. Caption of the document to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`): Optional. |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         document_url (:obj:`str`): A valid URL for the file.
         mime_type (:obj:`str`): Mime type of the content of the file, either "application/pdf"
             or "application/zip".

telegram/_inline/inlinequeryresultgif.py

@@ -51,12 +51,8 @@ class InlineQueryResultGif(InlineQueryResult):
         caption (:obj:`str`, optional): Caption of the GIF file to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -76,12 +72,8 @@ class InlineQueryResultGif(InlineQueryResult):
         caption (:obj:`str`): Optional. Caption of the GIF file to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`): Optional. |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

telegram/_inline/inlinequeryresultmpeg4gif.py

@@ -51,12 +51,8 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult):
         caption (:obj:`str`, optional): Caption of the MPEG-4 file to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -76,12 +72,8 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult):
         caption (:obj:`str`): Optional. Caption of the MPEG-4 file to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`): Optional. |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

telegram/_inline/inlinequeryresultphoto.py

@@ -49,12 +49,8 @@ class InlineQueryResultPhoto(InlineQueryResult):
         caption (:obj:`str`, optional): Caption of the photo to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -73,12 +69,8 @@ class InlineQueryResultPhoto(InlineQueryResult):
         caption (:obj:`str`): Optional. Caption of the photo to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`): Optional. |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the

telegram/_inline/inlinequeryresultvideo.py

@@ -51,12 +51,8 @@ class InlineQueryResultVideo(InlineQueryResult):
         caption (:obj:`str`, optional): Caption,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         video_width (:obj:`int`, optional): Video width.
         video_height (:obj:`int`, optional): Video height.
         video_duration (:obj:`int`, optional): Video duration in seconds.
@@ -75,22 +71,18 @@ class InlineQueryResultVideo(InlineQueryResult):
         mime_type (:obj:`str`): Mime type of the content of video url, "text/html" or "video/mp4".
         thumb_url (:obj:`str`): URL of the thumbnail (JPEG only) for the video.
         title (:obj:`str`): Title for the result.
-        caption (:obj:`str`): Optional. Caption of the video to be sent,
+        caption (:obj:`str`, optional): Caption of the video to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
+        video_width (:obj:`int`, optional): Video width.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
+        video_height (:obj:`int`, optional): Video height.
-            entities that appear in the caption, which can be specified instead of
+        video_duration (:obj:`int`, optional): Video duration in seconds.
-            :paramref:`parse_mode`.
+        description (:obj:`str`, optional): Short description of the result.
-        video_width (:obj:`int`): Optional. Video width.
+        reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
-        video_height (:obj:`int`): Optional. Video height.
-        video_duration (:obj:`int`): Optional. Video duration in seconds.
-        description (:obj:`str`): Optional. Short description of the result.
-        reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
-        input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
+        input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
             message to be sent instead of the video. This field is required if
             InlineQueryResultVideo is used to send an HTML-page as a result
             (e.g., a YouTube video).

telegram/_inline/inlinequeryresultvoice.py

@@ -45,12 +45,8 @@ class InlineQueryResultVoice(InlineQueryResult):
         caption (:obj:`str`, optional): Caption,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         voice_duration (:obj:`int`, optional): Recording duration in seconds.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
@@ -65,12 +61,8 @@ class InlineQueryResultVoice(InlineQueryResult):
         caption (:obj:`str`): Optional. Caption,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`): Optional. |parse_mode|
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         voice_duration (:obj:`int`): Optional. Recording duration in seconds.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.

telegram/_inline/inputtextmessagecontent.py

@@ -40,12 +40,8 @@ class InputTextMessageContent(InputMessageContent):
         message_text (:obj:`str`): Text of the message to be sent,
             1-:tg-const:`telegram.constants.MessageLimit.TEXT_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            bold, italic, fixed-width text or inline URLs in your bot's message. See the constants
+        entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         disable_web_page_preview (:obj:`bool`, optional): Disables link previews for links in the
             sent message.
 
@@ -53,12 +49,8 @@ class InputTextMessageContent(InputMessageContent):
         message_text (:obj:`str`): Text of the message to be sent,
             1-:tg-const:`telegram.constants.MessageLimit.TEXT_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+        parse_mode (:obj:`str`): Optional. |parse_mode|
-            bold, italic, fixed-width text or inline URLs in your bot's message. See the constants
+        entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
         disable_web_page_preview (:obj:`bool`): Optional. Disables link previews for links in the
             sent message.
 

telegram/_passport/credentials.py

@@ -245,25 +245,25 @@ class SecureData(TelegramObject):
     All fields are optional and depend on fields that were requested.
 
     Attributes:
-        personal_details (:class:`telegram.SecureValue`, optional): Credentials for encrypted
+        personal_details (:class:`telegram.SecureValue`): Optional. Credentials for encrypted
             personal details.
-        passport (:class:`telegram.SecureValue`, optional): Credentials for encrypted passport.
+        passport (:class:`telegram.SecureValue`): Optional. Credentials for encrypted passport.
-        internal_passport (:class:`telegram.SecureValue`, optional): Credentials for encrypted
+        internal_passport (:class:`telegram.SecureValue`): Optional. Credentials for encrypted
             internal passport.
-        driver_license (:class:`telegram.SecureValue`, optional): Credentials for encrypted
+        driver_license (:class:`telegram.SecureValue`): Optional. Credentials for encrypted
             driver license.
-        identity_card (:class:`telegram.SecureValue`, optional): Credentials for encrypted ID card
+        identity_card (:class:`telegram.SecureValue`): Optional. Credentials for encrypted ID card
-        address (:class:`telegram.SecureValue`, optional): Credentials for encrypted
+        address (:class:`telegram.SecureValue`): Optional. Credentials for encrypted
             residential address.
-        utility_bill (:class:`telegram.SecureValue`, optional): Credentials for encrypted
+        utility_bill (:class:`telegram.SecureValue`): Optional. Credentials for encrypted
             utility bill.
-        bank_statement (:class:`telegram.SecureValue`, optional): Credentials for encrypted
+        bank_statement (:class:`telegram.SecureValue`): Optional. Credentials for encrypted
             bank statement.
-        rental_agreement (:class:`telegram.SecureValue`, optional): Credentials for encrypted
+        rental_agreement (:class:`telegram.SecureValue`): Optional. Credentials for encrypted
             rental agreement.
-        passport_registration (:class:`telegram.SecureValue`, optional): Credentials for encrypted
+        passport_registration (:class:`telegram.SecureValue`): Optional. Credentials for encrypted
             registration from internal passport.
-        temporary_registration (:class:`telegram.SecureValue`, optional): Credentials for encrypted
+        temporary_registration (:class:`telegram.SecureValue`): Optional. Credentials for encrypted
             temporary registration.
     """
 
@@ -345,22 +345,22 @@ class SecureValue(TelegramObject):
     All fields are optional and depend on the type of field.
 
     Attributes:
-        data (:class:`telegram.DataCredentials`, optional): Credentials for encrypted Telegram
+        data (:class:`telegram.DataCredentials`): Optional. Credentials for encrypted Telegram
             Passport data. Available for "personal_details", "passport", "driver_license",
             "identity_card", "identity_passport" and "address" types.
-        front_side (:class:`telegram.FileCredentials`, optional): Credentials for encrypted
+        front_side (:class:`telegram.FileCredentials`): Optional. Credentials for encrypted
             document's front side. Available for "passport", "driver_license", "identity_card"
             and "internal_passport".
-        reverse_side (:class:`telegram.FileCredentials`, optional): Credentials for encrypted
+        reverse_side (:class:`telegram.FileCredentials`): Optional. Credentials for encrypted
             document's reverse side. Available for "driver_license" and "identity_card".
-        selfie (:class:`telegram.FileCredentials`, optional): Credentials for encrypted selfie
+        selfie (:class:`telegram.FileCredentials`): Optional. Credentials for encrypted selfie
             of the user with a document. Can be available for "passport", "driver_license",
             "identity_card" and "internal_passport".
-        translation (List[:class:`telegram.FileCredentials`], optional): Credentials for an
+        translation (List[:class:`telegram.FileCredentials`]): Optional. Credentials for an
             encrypted translation of the document. Available for "passport", "driver_license",
             "identity_card", "internal_passport", "utility_bill", "bank_statement",
             "rental_agreement", "passport_registration" and "temporary_registration".
-        files (List[:class:`telegram.FileCredentials`], optional): Credentials for encrypted
+        files (List[:class:`telegram.FileCredentials`]): Optional. Credentials for encrypted
             files. Available for "utility_bill", "bank_statement", "rental_agreement",
             "passport_registration" and "temporary_registration" types.
 

telegram/_poll.py

@@ -152,7 +152,7 @@ class Poll(TelegramObject):
         is_anonymous (:obj:`bool`): :obj:`True`, if the poll is anonymous.
         type (:obj:`str`): Poll type, currently can be :attr:`REGULAR` or :attr:`QUIZ`.
         allows_multiple_answers (:obj:`bool`): :obj:`True`, if the poll allows multiple answers.
-        correct_option_id (:obj:`int`, optional): A zero based identifier of the correct answer
+        correct_option_id (:obj:`int`): Optional. A zero based identifier of the correct answer
             option. Available only for closed polls in the quiz mode, which were sent
             (not forwarded), by the bot or to a private chat with the bot.
         explanation (:obj:`str`): Optional. Text that is shown when a user chooses an incorrect

telegram/ext/_application.py

@@ -638,7 +638,7 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
             allowed_updates (List[:obj:`str`], optional): Passed to
                 :meth:`telegram.Bot.get_updates`.
             close_loop (:obj:`bool`, optional): If :obj:`True`, the current event loop will be
-                closed upon shutdown.
+                closed upon shutdown. Defaults to :obj:`True`.
 
                 .. seealso::
                     :meth:`asyncio.loop.close`

telegram/ext/_chatmemberhandler.py

@@ -62,7 +62,7 @@ class ChatMemberHandler(BaseHandler[Update, CCT]):
 
     Attributes:
         callback (:term:`coroutine function`): The callback function for this handler.
-        chat_member_types (:obj:`int`, optional): Specifies if this handler should handle
+        chat_member_types (:obj:`int`): Optional. Specifies if this handler should handle
             only updates with :attr:`telegram.Update.my_chat_member`,
             :attr:`telegram.Update.chat_member` or both.
         block (:obj:`bool`): Determines whether the return value of the callback should be

telegram/ext/_commandhandler.py

@@ -16,7 +16,7 @@
 #
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
-"""This module contains the CommandHandler and PrefixHandler classes."""
+"""This module contains the CommandHandler class."""
 import re
 from typing import TYPE_CHECKING, Dict, List, Optional, Tuple, TypeVar, Union
 

telegram/ext/_defaults.py

@@ -36,15 +36,11 @@ class Defaults:
         networking backend directly via :class:`telegram.ext.ApplicationBuilder` instead.
 
     Parameters:
-        parse_mode (:obj:`str`, optional): Send :attr:`~telegram.constants.ParseMode.MARKDOWN` or
+        parse_mode (:obj:`str`, optional): |parse_mode|
-            :attr:`~telegram.constants.ParseMode.HTML`, if you want Telegram apps to show
+        disable_notification (:obj:`bool`, optional): |disable_notification|
-            bold, italic, fixed-width text or URLs in your bot's message.
-        disable_notification (:obj:`bool`, optional): Sends the message silently. Users will
-            receive a notification with no sound.
         disable_web_page_preview (:obj:`bool`, optional): Disables link previews for links in this
             message.
-        allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message
+        allow_sending_without_reply (:obj:`bool`, optional): |allow_sending_without_reply|
-            should be sent even if the specified replied-to message is not found.
         quote (:obj:`bool`, optional): If set to :obj:`True`, the reply is sent as an actual reply
             to the message. If ``reply_to_message_id`` is passed, this parameter will
             be ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
@@ -58,8 +54,7 @@ class Defaults:
             parameter
             of handlers and error handlers registered through :meth:`Application.add_handler` and
             :meth:`Application.add_error_handler`. Defaults to :obj:`True`.
-        protect_content (:obj:`bool`, optional): Protects the contents of the sent message from
+        protect_content (:obj:`bool`, optional): |protect_content|
-            forwarding and saving.
 
             .. versionadded:: 20.0
     """

telegram/ext/_picklepersistence.py

@@ -175,7 +175,7 @@ class PicklePersistence(BasePersistence[UD, CD, BD]):
         single_file (:obj:`bool`): Optional. When :obj:`False` will store 5 separate files of
             `filename_user_data`, `filename_bot_data`, `filename_chat_data`,
             `filename_callback_data` and `filename_conversations`. Default is :obj:`True`.
-        on_flush (:obj:`bool`, optional): When :obj:`True` will only save to file when
+        on_flush (:obj:`bool`): Optional. When :obj:`True` will only save to file when
             :meth:`flush` is called and keep data in memory until that happens. When
             :obj:`False` will store data on any transaction *and* on call to :meth:`flush`.
             Default is :obj:`False`.