Documentation Improvements (#2693, #2691, #2739)

.github/CONTRIBUTING.rst

@@ -137,6 +137,8 @@ Here's how to make a one-off code change.
 
        - Make a new commit addressing the comments you agree with, and push it to the same branch. Ideally, the commit message would explain what the commit does (e.g. "Fix lint error"), but if there are lots of disparate review comments, it's fine to refer to the original commit message and add something like "(address review comments)".
 
+       - In order to keep the commit history intact, please avoid squashing or amending history and then force-pushing to the PR. Reviewers often want to look at individual commits.
+
        - In addition, please reply to each comment. Each reply should be either "Done" or a response explaining why the corresponding suggestion wasn't implemented. All comments must be resolved before LGTM can be given.
 
    - Resolve any merge conflicts that arise. To resolve conflicts between 'your-branch-name' (in your fork) and 'master' (in the ``python-telegram-bot`` repository), run:

README.rst

@@ -167,8 +167,8 @@ Learning by example
 
 We believe that the best way to learn this package is by example. Here
 are some examples for you to review. Even if it is not your approach for learning, please take a
-look at ``echobot.py``, it is the de facto base for most of the bots out there. Best of all,
+look at ``echobot.py``. It is the de facto base for most of the bots out there. Best of all,
-the code for these examples are released to the public domain, so you can start by grabbing the
+the code for these examples is released to the public domain, so you can start by grabbing the
 code and building on top of it.
 
 Visit `this page <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/README.md>`_ to discover the official examples or look at the examples on the `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Examples>`_ to see other bots the community has built.
@@ -231,7 +231,7 @@ Contributions of all sizes are welcome. Please review our `contribution guidelin
 ========
 Donating
 ========
-Occasionally we are asked if we accept donations to support the development. While we appreciate the thought, maintaining PTB is our hobby and we have almost no running costs for it. We therefore have nothing set up to accept donations. If you still want to donate, we kindly ask you to donate to another open source project/initiative of your choice instead.
+Occasionally we are asked if we accept donations to support the development. While we appreciate the thought, maintaining PTB is our hobby, and we have almost no running costs for it. We therefore have nothing set up to accept donations. If you still want to donate, we kindly ask you to donate to another open source project/initiative of your choice instead.
 
 =======
 License

README_RAW.rst

@@ -213,7 +213,7 @@ Contributions of all sizes are welcome. Please review our `contribution guidelin
 ========
 Donating
 ========
-Occasionally we are asked if we accept donations to support the development. While we appreciate the thought, maintaining PTB is our hobby and we have almost no running costs for it. We therefore have nothing set up to accept donations. If you still want to donate, we kindly ask you to donate to another open source project/initiative of your choice instead.
+Occasionally we are asked if we accept donations to support the development. While we appreciate the thought, maintaining PTB is our hobby, and we have almost no running costs for it. We therefore have nothing set up to accept donations. If you still want to donate, we kindly ask you to donate to another open source project/initiative of your choice instead.
 
 =======
 License

docs/source/conf.py

@@ -38,8 +38,16 @@ needs_sphinx = '4.2.0'
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
-    'sphinx.ext.napoleon'
+    'sphinx.ext.napoleon',
+    'sphinx.ext.intersphinx'
 ]
+
+# Use intersphinx to reference the python builtin library docs
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'APScheduler': ('https://apscheduler.readthedocs.io/en/3.x/', None)
+}
+
 # Don't show type hints in the signature - that just makes it hardly readable
 # and we document the types anyway
 autodoc_typehints = 'none'

telegram/_callbackquery.py

@@ -47,7 +47,7 @@ class CallbackQuery(TelegramObject):
     considered equal, if their :attr:`id` is equal.
 
     Note:
-        * In Python ``from`` is a reserved word, use ``from_user`` instead.
+        * In Python :keyword:`from` is a reserved word, use ``from_user`` instead.
         * Exactly one of the fields :attr:`data` or :attr:`game_short_name` will be present.
         * After the user presses an inline button, Telegram clients will display a progress bar
           until you call :attr:`answer`. It is, therefore, necessary to react

telegram/_chatmemberupdated.py

@@ -38,7 +38,7 @@ class ChatMemberUpdated(TelegramObject):
     .. versionadded:: 13.4
 
     Note:
-        In Python ``from`` is a reserved word, use ``from_user`` instead.
+        In Python :keyword:`from` is a reserved word, use ``from_user`` instead.
 
     Args:
         chat (:class:`telegram.Chat`): Chat the user belongs to.

telegram/_choseninlineresult.py

@@ -37,7 +37,7 @@ class ChosenInlineResult(TelegramObject):
     considered equal, if their :attr:`result_id` is equal.
 
     Note:
-        * In Python ``from`` is a reserved word, use ``from_user`` instead.
+        * In Python :keyword:`from` is a reserved word, use ``from_user`` instead.
         * It is necessary to enable inline feedback via `@Botfather <https://t.me/BotFather>`_ in
           order to receive these objects in updates.
 

telegram/_files/animation.py

@@ -44,7 +44,7 @@ class Animation(_BaseThumbedMedium):
         thumb (:class:`telegram.PhotoSize`, optional): Animation thumbnail as defined by sender.
         file_name (:obj:`str`, optional): Original animation filename as defined by sender.
         mime_type (:obj:`str`, optional): MIME type of the file as defined by sender.
-        file_size (:obj:`int`, optional): File size.
+        file_size (:obj:`int`, optional): File size in bytes.
         bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
@@ -59,7 +59,7 @@ class Animation(_BaseThumbedMedium):
         thumb (:class:`telegram.PhotoSize`): Optional. Animation thumbnail as defined by sender.
         file_name (:obj:`str`): Optional. Original animation filename as defined by sender.
         mime_type (:obj:`str`): Optional. MIME type of the file as defined by sender.
-        file_size (:obj:`int`): Optional. File size.
+        file_size (:obj:`int`): Optional. File size in bytes.
         bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
 
     """

telegram/_files/audio.py

@@ -44,7 +44,7 @@ class Audio(_BaseThumbedMedium):
         title (:obj:`str`, optional): Title of the audio as defined by sender or by audio tags.
         file_name (:obj:`str`, optional): Original filename as defined by sender.
         mime_type (:obj:`str`, optional): MIME type of the file as defined by sender.
-        file_size (:obj:`int`, optional): File size.
+        file_size (:obj:`int`, optional): File size in bytes.
         thumb (:class:`telegram.PhotoSize`, optional): Thumbnail of the album cover to
             which the music file belongs.
         bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
@@ -61,7 +61,7 @@ class Audio(_BaseThumbedMedium):
         title (:obj:`str`): Optional. Title of the audio as defined by sender or by audio tags.
         file_name (:obj:`str`): Optional. Original filename as defined by sender.
         mime_type (:obj:`str`): Optional. MIME type of the file as defined by sender.
-        file_size (:obj:`int`): Optional. File size.
+        file_size (:obj:`int`): Optional. File size in bytes.
         thumb (:class:`telegram.PhotoSize`): Optional. Thumbnail of the album cover to
             which the music file belongs.
         bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.

telegram/_files/document.py

@@ -42,7 +42,7 @@ class Document(_BaseThumbedMedium):
         thumb (:class:`telegram.PhotoSize`, optional): Document thumbnail as defined by sender.
         file_name (:obj:`str`, optional): Original filename as defined by sender.
         mime_type (:obj:`str`, optional): MIME type of the file as defined by sender.
-        file_size (:obj:`int`, optional): File size.
+        file_size (:obj:`int`, optional): File size in bytes.
         bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
@@ -54,7 +54,7 @@ class Document(_BaseThumbedMedium):
         thumb (:class:`telegram.PhotoSize`): Optional. Document thumbnail.
         file_name (:obj:`str`): Original filename.
         mime_type (:obj:`str`): Optional. MIME type of the file.
-        file_size (:obj:`int`): Optional. File size.
+        file_size (:obj:`int`): Optional. File size in bytes.
         bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
 
     """

telegram/_files/file.py

@@ -53,7 +53,7 @@ class File(TelegramObject):
         file_unique_id (:obj:`str`): Unique identifier for this file, which
             is supposed to be the same over time and for different bots.
             Can't be used to download or reuse the file.
-        file_size (:obj:`int`, optional): Optional. File size, if known.
+        file_size (:obj:`int`, optional): Optional. File size in bytes, if known.
         file_path (:obj:`str`, optional): File path. Use :attr:`download` to get the file.
         bot (:obj:`telegram.Bot`, optional): Bot to use with shortcut method.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
@@ -63,7 +63,7 @@ class File(TelegramObject):
         file_unique_id (:obj:`str`): Unique identifier for this file, which
             is supposed to be the same over time and for different bots.
             Can't be used to download or reuse the file.
-        file_size (:obj:`str`): Optional. File size.
+        file_size (:obj:`str`): Optional. File size in bytes.
         file_path (:obj:`str`): Optional. File path. Use :attr:`download` to get the file.
 
     """

telegram/_files/inputmedia.py

@@ -146,7 +146,7 @@ class InputMediaAnimation(InputMedia):
             entities that appear in the caption, which can be specified instead of parse_mode.
         width (:obj:`int`, optional): Animation width.
         height (:obj:`int`, optional): Animation height.
-        duration (:obj:`int`, optional): Animation duration.
+        duration (:obj:`int`, optional): Animation duration in seconds.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InputMediaType.ANIMATION`.
@@ -158,7 +158,7 @@ class InputMediaAnimation(InputMedia):
         thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send.
         width (:obj:`int`): Optional. Animation width.
         height (:obj:`int`): Optional. Animation height.
-        duration (:obj:`int`): Optional. Animation duration.
+        duration (:obj:`int`): Optional. Animation duration in seconds.
 
     """
 
@@ -276,7 +276,7 @@ class InputMediaVideo(InputMedia):
             entities that appear in the caption, which can be specified instead of parse_mode.
         width (:obj:`int`, optional): Video width.
         height (:obj:`int`, optional): Video height.
-        duration (:obj:`int`, optional): Video duration.
+        duration (:obj:`int`, optional): Video duration in seconds.
         supports_streaming (:obj:`bool`, optional): Pass :obj:`True`, if the uploaded video is
             suitable for streaming.
         thumb (`filelike object` | :obj:`bytes` | :class:`pathlib.Path`, optional): Thumbnail of
@@ -298,7 +298,7 @@ class InputMediaVideo(InputMedia):
             entities that appear in the caption.
         width (:obj:`int`): Optional. Video width.
         height (:obj:`int`): Optional. Video height.
-        duration (:obj:`int`): Optional. Video duration.
+        duration (:obj:`int`): Optional. Video duration in seconds.
         supports_streaming (:obj:`bool`): Optional. Pass :obj:`True`, if the uploaded video is
             suitable for streaming.
         thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send.

telegram/_files/photosize.py

@@ -40,7 +40,7 @@ class PhotoSize(_BaseMedium):
             Can't be used to download or reuse the file.
         width (:obj:`int`): Photo width.
         height (:obj:`int`): Photo height.
-        file_size (:obj:`int`, optional): File size.
+        file_size (:obj:`int`, optional): File size in bytes.
         bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
@@ -51,7 +51,7 @@ class PhotoSize(_BaseMedium):
             Can't be used to download or reuse the file.
         width (:obj:`int`): Photo width.
         height (:obj:`int`): Photo height.
-        file_size (:obj:`int`): Optional. File size.
+        file_size (:obj:`int`): Optional. File size in bytes.
         bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
 
     """

telegram/_files/sticker.py

@@ -58,7 +58,7 @@ class Sticker(_BaseThumbedMedium):
             belongs.
         mask_position (:class:`telegram.MaskPosition`, optional): For mask stickers, the
             position where the mask should be placed.
-        file_size (:obj:`int`, optional): File size.
+        file_size (:obj:`int`, optional): File size in bytes.
         bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
         **kwargs (obj:`dict`): Arbitrary keyword arguments.
 
@@ -79,7 +79,7 @@ class Sticker(_BaseThumbedMedium):
         set_name (:obj:`str`): Optional. Name of the sticker set to which the sticker belongs.
         mask_position (:class:`telegram.MaskPosition`): Optional. For mask stickers, the position
             where the mask should be placed.
-        file_size (:obj:`int`): Optional. File size.
+        file_size (:obj:`int`): Optional. File size in bytes.
         bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
 
     """

telegram/_files/video.py

@@ -45,7 +45,7 @@ class Video(_BaseThumbedMedium):
         thumb (:class:`telegram.PhotoSize`, optional): Video thumbnail.
         file_name (:obj:`str`, optional): Original filename as defined by sender.
         mime_type (:obj:`str`, optional): Mime type of a file as defined by sender.
-        file_size (:obj:`int`, optional): File size.
+        file_size (:obj:`int`, optional): File size in bytes.
         bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
@@ -60,7 +60,7 @@ class Video(_BaseThumbedMedium):
         thumb (:class:`telegram.PhotoSize`): Optional. Video thumbnail.
         file_name (:obj:`str`): Optional. Original filename as defined by sender.
         mime_type (:obj:`str`): Optional. Mime type of a file as defined by sender.
-        file_size (:obj:`int`): Optional. File size.
+        file_size (:obj:`int`): Optional. File size in bytes.
         bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
 
     """

telegram/_files/videonote.py

@@ -43,7 +43,7 @@ class VideoNote(_BaseThumbedMedium):
             by sender.
         duration (:obj:`int`): Duration of the video in seconds as defined by sender.
         thumb (:class:`telegram.PhotoSize`, optional): Video thumbnail.
-        file_size (:obj:`int`, optional): File size.
+        file_size (:obj:`int`, optional): File size in bytes.
         bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
@@ -55,7 +55,7 @@ class VideoNote(_BaseThumbedMedium):
         length (:obj:`int`): Video width and height as defined by sender.
         duration (:obj:`int`): Duration of the video in seconds as defined by sender.
         thumb (:class:`telegram.PhotoSize`): Optional. Video thumbnail.
-        file_size (:obj:`int`): Optional. File size.
+        file_size (:obj:`int`): Optional. File size in bytes.
         bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
 
     """

telegram/_files/voice.py

@@ -40,7 +40,7 @@ class Voice(_BaseMedium):
             Can't be used to download or reuse the file.
         duration (:obj:`int`, optional): Duration of the audio in seconds as defined by sender.
         mime_type (:obj:`str`, optional): MIME type of the file as defined by sender.
-        file_size (:obj:`int`, optional): File size.
+        file_size (:obj:`int`, optional): File size in bytes.
         bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
@@ -51,7 +51,7 @@ class Voice(_BaseMedium):
             Can't be used to download or reuse the file.
         duration (:obj:`int`): Duration of the audio in seconds as defined by sender.
         mime_type (:obj:`str`): Optional. MIME type of the file as defined by sender.
-        file_size (:obj:`int`): Optional. File size.
+        file_size (:obj:`int`): Optional. File size in bytes.
         bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
 
     """

telegram/_inline/inlinequery.py

@@ -38,7 +38,7 @@ class InlineQuery(TelegramObject):
     considered equal, if their :attr:`id` is equal.
 
     Note:
-        In Python ``from`` is a reserved word, use ``from_user`` instead.
+        In Python :keyword:`from` is a reserved word, use ``from_user`` instead.
 
     Args:
         id (:obj:`str`): Unique identifier for this query.

telegram/_inline/inlinequeryresultdocument.py

@@ -56,7 +56,7 @@ class InlineQueryResultDocument(InlineQueryResult):
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
             message to be sent instead of the file.
-        thumb_url (:obj:`str`, optional): URL of the thumbnail (jpeg only) for the file.
+        thumb_url (:obj:`str`, optional): URL of the thumbnail (JPEG only) for the file.
         thumb_width (:obj:`int`, optional): Thumbnail width.
         thumb_height (:obj:`int`, optional): Thumbnail height.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
@@ -82,7 +82,7 @@ class InlineQueryResultDocument(InlineQueryResult):
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
             message to be sent instead of the file.
-        thumb_url (:obj:`str`): Optional. URL of the thumbnail (jpeg only) for the file.
+        thumb_url (:obj:`str`): Optional. URL of the thumbnail (JPEG only) for the file.
         thumb_width (:obj:`int`): Optional. Thumbnail width.
         thumb_height (:obj:`int`): Optional. Thumbnail height.
 

telegram/_inline/inlinequeryresultgif.py

@@ -41,7 +41,7 @@ class InlineQueryResultGif(InlineQueryResult):
         gif_url (:obj:`str`): A valid URL for the GIF file. File size must not exceed 1MB.
         gif_width (:obj:`int`, optional): Width of the GIF.
         gif_height (:obj:`int`, optional): Height of the GIF.
-        gif_duration (:obj:`int`, optional): Duration of the GIF
+        gif_duration (:obj:`int`, optional): Duration of the GIF in seconds.
         thumb_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for
             the result.
         thumb_mime_type (:obj:`str`, optional): MIME type of the thumbnail, must be one of
@@ -68,7 +68,7 @@ class InlineQueryResultGif(InlineQueryResult):
         gif_url (:obj:`str`): A valid URL for the GIF file. File size must not exceed 1MB.
         gif_width (:obj:`int`): Optional. Width of the GIF.
         gif_height (:obj:`int`): Optional. Height of the GIF.
-        gif_duration (:obj:`int`): Optional. Duration of the GIF.
+        gif_duration (:obj:`int`): Optional. Duration of the GIF in seconds.
         thumb_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for
             the result.
         thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail.

telegram/_inline/inlinequeryresultmpeg4gif.py

@@ -41,7 +41,7 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult):
         mpeg4_url (:obj:`str`): A valid URL for the MP4 file. File size must not exceed 1MB.
         mpeg4_width (:obj:`int`, optional): Video width.
         mpeg4_height (:obj:`int`, optional): Video height.
-        mpeg4_duration (:obj:`int`, optional): Video duration.
+        mpeg4_duration (:obj:`int`, optional): Video duration in seconds.
         thumb_url (:obj:`str`): URL of the static thumbnail (jpeg or gif) for the result.
         thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail, must be one of
             ``'image/jpeg'``, ``'image/gif'``, or ``'video/mp4'``. Defaults to ``'image/jpeg'``.
@@ -67,7 +67,7 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult):
         mpeg4_url (:obj:`str`): A valid URL for the MP4 file. File size must not exceed 1MB.
         mpeg4_width (:obj:`int`): Optional. Video width.
         mpeg4_height (:obj:`int`): Optional. Video height.
-        mpeg4_duration (:obj:`int`): Optional. Video duration.
+        mpeg4_duration (:obj:`int`): Optional. Video duration in seconds.
         thumb_url (:obj:`str`): URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail for
             the result.
         thumb_mime_type (:obj:`str`): Optional. MIME type of the thumbnail.

telegram/_inline/inlinequeryresultphoto.py

@@ -37,7 +37,7 @@ class InlineQueryResultPhoto(InlineQueryResult):
 
     Args:
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
-        photo_url (:obj:`str`): A valid URL of the photo. Photo must be in jpeg format. Photo size
+        photo_url (:obj:`str`): A valid URL of the photo. Photo must be in JPEG format. Photo size
             must not exceed 5MB.
         thumb_url (:obj:`str`): URL of the thumbnail for the photo.
         photo_width (:obj:`int`, optional): Width of the photo.
@@ -62,7 +62,7 @@ class InlineQueryResultPhoto(InlineQueryResult):
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.PHOTO`.
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
-        photo_url (:obj:`str`): A valid URL of the photo. Photo must be in jpeg format. Photo size
+        photo_url (:obj:`str`): A valid URL of the photo. Photo must be in JPEG format. Photo size
             must not exceed 5MB.
         thumb_url (:obj:`str`): URL of the thumbnail for the photo.
         photo_width (:obj:`int`): Optional. Width of the photo.

telegram/_inline/inlinequeryresultvideo.py

@@ -44,7 +44,7 @@ class InlineQueryResultVideo(InlineQueryResult):
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         video_url (:obj:`str`): A valid URL for the embedded video player or video file.
         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.
+        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,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
@@ -72,7 +72,7 @@ class InlineQueryResultVideo(InlineQueryResult):
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         video_url (:obj:`str`): A valid URL for the embedded video player or video file.
         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.
+        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,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after

telegram/_message.py

@@ -82,7 +82,7 @@ class Message(TelegramObject):
     considered equal, if their :attr:`message_id` and :attr:`chat` are equal.
 
     Note:
-        In Python ``from`` is a reserved word, use ``from_user`` instead.
+        In Python :keyword:`from` is a reserved word, use ``from_user`` instead.
 
     Args:
         message_id (:obj:`int`): Unique message identifier inside this chat.

telegram/_passport/passportfile.py

@@ -42,7 +42,7 @@ class PassportFile(TelegramObject):
         file_unique_id (:obj:`str`): Unique identifier for this file, which
             is supposed to be the same over time and for different bots.
             Can't be used to download or reuse the file.
-        file_size (:obj:`int`): File size.
+        file_size (:obj:`int`): File size in bytes.
         file_date (:obj:`int`): Unix time when the file was uploaded.
         bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
@@ -52,7 +52,7 @@ class PassportFile(TelegramObject):
         file_unique_id (:obj:`str`): Unique identifier for this file, which
             is supposed to be the same over time and for different bots.
             Can't be used to download or reuse the file.
-        file_size (:obj:`int`): File size.
+        file_size (:obj:`int`): File size in bytes.
         file_date (:obj:`int`): Unix time when the file was uploaded.
         bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
 

telegram/_payment/precheckoutquery.py

@@ -35,7 +35,7 @@ class PreCheckoutQuery(TelegramObject):
     considered equal, if their :attr:`id` is equal.
 
     Note:
-        In Python ``from`` is a reserved word, use ``from_user`` instead.
+        In Python :keyword:`from` is a reserved word, use ``from_user`` instead.
 
     Args:
         id (:obj:`str`): Unique query identifier.

telegram/_payment/shippingquery.py

@@ -35,7 +35,7 @@ class ShippingQuery(TelegramObject):
     considered equal, if their :attr:`id` is equal.
 
     Note:
-        In Python ``from`` is a reserved word, use ``from_user`` instead.
+        In Python :keyword:`from` is a reserved word, use ``from_user`` instead.
 
     Args:
         id (:obj:`str`): Unique query identifier.

telegram/_poll.py

@@ -67,17 +67,17 @@ class PollAnswer(TelegramObject):
     Objects of this class are comparable in terms of equality. Two objects of this class are
     considered equal, if their :attr:`poll_id`, :attr:`user` and :attr:`options_ids` are equal.
 
-    Attributes:
-        poll_id (:obj:`str`): Unique poll identifier.
-        user (:class:`telegram.User`): The user, who changed the answer to the poll.
-        option_ids (List[:obj:`int`]): Identifiers of answer options, chosen by the user.
-
     Args:
         poll_id (:obj:`str`): Unique poll identifier.
         user (:class:`telegram.User`): The user, who changed the answer to the poll.
         option_ids (List[:obj:`int`]): 0-based identifiers of answer options, chosen by the user.
             May be empty if the user retracted their vote.
 
+    Attributes:
+        poll_id (:obj:`str`): Unique poll identifier.
+        user (:class:`telegram.User`): The user, who changed the answer to the poll.
+        option_ids (List[:obj:`int`]): Identifiers of answer options, chosen by the user.
+
     """
 
     __slots__ = ('option_ids', 'user', 'poll_id')
@@ -109,25 +109,6 @@ class Poll(TelegramObject):
     Objects of this class are comparable in terms of equality. Two objects of this class are
     considered equal, if their :attr:`id` is equal.
 
-    Attributes:
-        id (:obj:`str`): Unique poll identifier.
-        question (:obj:`str`): Poll question, 1-300 characters.
-        options (List[:class:`PollOption`]): List of poll options.
-        total_voter_count (:obj:`int`): Total number of users that voted in the poll.
-        is_closed (:obj:`bool`): :obj:`True`, if the poll is closed.
-        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. Identifier of the correct answer option.
-        explanation (:obj:`str`): Optional. Text that is shown when a user chooses an incorrect
-            answer or taps on the lamp icon in a quiz-style poll.
-        explanation_entities (List[:class:`telegram.MessageEntity`]): Optional. Special entities
-            like usernames, URLs, bot commands, etc. that appear in the :attr:`explanation`.
-        open_period (:obj:`int`): Optional. Amount of time in seconds the poll will be active
-            after creation.
-        close_date (:obj:`datetime.datetime`): Optional. Point in time when the poll will be
-            automatically closed.
-
     Args:
         id (:obj:`str`): Unique poll identifier.
         question (:obj:`str`): Poll question, 1-300 characters.
@@ -148,6 +129,25 @@ class Poll(TelegramObject):
         close_date (:obj:`datetime.datetime`, optional): Point in time (Unix timestamp) when the
             poll will be automatically closed. Converted to :obj:`datetime.datetime`.
 
+    Attributes:
+        id (:obj:`str`): Unique poll identifier.
+        question (:obj:`str`): Poll question, 1-300 characters.
+        options (List[:class:`PollOption`]): List of poll options.
+        total_voter_count (:obj:`int`): Total number of users that voted in the poll.
+        is_closed (:obj:`bool`): :obj:`True`, if the poll is closed.
+        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. Identifier of the correct answer option.
+        explanation (:obj:`str`): Optional. Text that is shown when a user chooses an incorrect
+            answer or taps on the lamp icon in a quiz-style poll.
+        explanation_entities (List[:class:`telegram.MessageEntity`]): Optional. Special entities
+            like usernames, URLs, bot commands, etc. that appear in the :attr:`explanation`.
+        open_period (:obj:`int`): Optional. Amount of time in seconds the poll will be active
+            after creation.
+        close_date (:obj:`datetime.datetime`): Optional. Point in time when the poll will be
+            automatically closed.
+
     """
 
     __slots__ = (

telegram/error.py

@@ -163,7 +163,12 @@ class Conflict(TelegramError):
 
 
 class PassportDecryptionError(TelegramError):
-    """Something went wrong with decryption."""
+    """Something went wrong with decryption.
+
+    .. versionchanged:: 14.0
+        This class was previously named ``TelegramDecryptionError`` and was available via
+        ``telegram.TelegramDecryptionError``.
+    """
 
     __slots__ = ('_msg',)
 

telegram/ext/_builders.py

@@ -823,7 +823,7 @@ class UpdaterBuilder(_BaseBuilder[ODT, BT, CCT, UD, CD, BD, JQ, PT]):
     Example:
         .. code:: python
 
-            dispatcher = UpdaterBuilder().token('TOKEN').build()
+            updater = UpdaterBuilder().token('TOKEN').build()
 
     Please see the description of the individual methods for information on which arguments can be
     set and what the defaults are when not called. When no default is mentioned, the argument will
@@ -1192,7 +1192,7 @@ class UpdaterBuilder(_BaseBuilder[ODT, BT, CCT, UD, CD, BD, JQ, PT]):
         dispatcher: Optional[Dispatcher[InBT, InCCT, InUD, InCD, InBD, InJQ, InPT]],
     ) -> 'UpdaterBuilder[Optional[Dispatcher[InBT, InCCT, InUD, InCD, InBD, InJQ, InPT]], InBT, InCCT, InUD, InCD, InBD, InJQ, InPT]':
         """Sets a :class:`telegram.ext.Dispatcher` instance to be used for
-        :attr:`telegram.ext.Updater.dispatcher`. If not called, a queue will be instantiated.
+        :attr:`telegram.ext.Updater.dispatcher`.
         The dispatchers :attr:`telegram.ext.Dispatcher.bot`,
         :attr:`telegram.ext.Dispatcher.update_queue` and
         :attr:`telegram.ext.Dispatcher.exception_event` will be used for the respective arguments

telegram/ext/_dispatcher.py

@@ -661,9 +661,8 @@ class Dispatcher(Generic[BT, CCT, UD, CD, BD, JQ, PT]):
         Args:
             callback (:obj:`callable`): The callback function for this error handler. Will be
                 called when an error is raised. Callback signature:
-                ``def callback(update: Update, context: CallbackContext)``
+                ``def callback(update: Update, context: CallbackContext)``.
-
+                The error that happened will be present in ``context.error``.
-                The error that happened will be present in context.error.
             run_async (:obj:`bool`, optional): Whether this handlers callback should be run
                 asynchronously using :meth:`run_async`. Defaults to :obj:`False`.
         """

telegram/ext/_jobqueue.py

@@ -116,11 +116,11 @@ class JobQueue:
         name: str = None,
         job_kwargs: JSONDict = None,
     ) -> 'Job':
-        """Creates a new ``Job`` that runs once and adds it to the queue.
+        """Creates a new :class:`Job` instance that runs once and adds it to the queue.
 
         Args:
             callback (:obj:`callable`): The callback function that should be executed by the new
-                job. Callback signature: ``def callback(update: Update, context: CallbackContext)``
+                job. Callback signature: ``def callback(context: CallbackContext)``
             when (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta` |                         \
                   :obj:`datetime.datetime` | :obj:`datetime.time`):
                 Time in or at which the job should run. This parameter will be interpreted
@@ -131,22 +131,23 @@ class JobQueue:
                 * :obj:`datetime.timedelta` will be interpreted as "time from now" in which the
                   job should run.
                 * :obj:`datetime.datetime` will be interpreted as a specific date and time at
-                  which the job should run. If the timezone (``datetime.tzinfo``) is :obj:`None`,
+                  which the job should run. If the timezone (:attr:`datetime.datetime.tzinfo`) is
-                  the default timezone of the bot will be used.
+                  :obj:`None`, the default timezone of the bot will be used.
                 * :obj:`datetime.time` will be interpreted as a specific time of day at which the
                   job should run. This could be either today or, if the time has already passed,
-                  tomorrow. If the timezone (``time.tzinfo``) is :obj:`None`, the
+                  tomorrow. If the timezone (:attr:`datetime.time.tzinfo`) is :obj:`None`, the
                   default timezone of the bot will be used.
 
             context (:obj:`object`, optional): Additional data needed for the callback function.
-                Can be accessed through ``job.context`` in the callback. Defaults to :obj:`None`.
+                Can be accessed through :attr:`Job.context` in the callback. Defaults to
+                :obj:`None`.
             name (:obj:`str`, optional): The name of the new job. Defaults to
                 ``callback.__name__``.
             job_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to pass to the
-                ``scheduler.add_job()``.
+                :meth:`apscheduler.schedulers.base.BaseScheduler.add_job()`.
 
         Returns:
-            :class:`telegram.ext.Job`: The new ``Job`` instance that has been added to the job
+            :class:`telegram.ext.Job`: The new :class:`Job` instance that has been added to the job
             queue.
 
         """
@@ -180,7 +181,8 @@ class JobQueue:
         name: str = None,
         job_kwargs: JSONDict = None,
     ) -> 'Job':
-        """Creates a new ``Job`` that runs at specified intervals and adds it to the queue.
+        """Creates a new :class:`Job` instance that runs at specified intervals and adds it to the
+            queue.
 
         Note:
             For a note about DST, please see the documentation of `APScheduler`_.
@@ -190,7 +192,7 @@ class JobQueue:
 
         Args:
             callback (:obj:`callable`): The callback function that should be executed by the new
-                job. Callback signature: ``def callback(update: Update, context: CallbackContext)``
+                job. Callback signature: ``def callback(context: CallbackContext)``
             interval (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta`): The interval in which
                 the job will run. If it is an :obj:`int` or a :obj:`float`, it will be interpreted
                 as seconds.
@@ -204,11 +206,11 @@ class JobQueue:
                 * :obj:`datetime.timedelta` will be interpreted as "time from now" in which the
                   job should run.
                 * :obj:`datetime.datetime` will be interpreted as a specific date and time at
-                  which the job should run. If the timezone (``datetime.tzinfo``) is :obj:`None`,
+                  which the job should run. If the timezone (:attr:`datetime.datetime.tzinfo`) is
-                  the default timezone of the bot will be used.
+                  :obj:`None`, the default timezone of the bot will be used.
                 * :obj:`datetime.time` will be interpreted as a specific time of day at which the
                   job should run. This could be either today or, if the time has already passed,
-                  tomorrow. If the timezone (``time.tzinfo``) is :obj:`None`, the
+                  tomorrow. If the timezone (:attr:`datetime.time.tzinfo`) is :obj:`None`, the
                   default timezone of the bot will be used.
 
                 Defaults to ``interval``
@@ -223,14 +225,15 @@ class JobQueue:
 
                 Defaults to :obj:`None`.
             context (:obj:`object`, optional): Additional data needed for the callback function.
-                Can be accessed through ``job.context`` in the callback. Defaults to :obj:`None`.
+                Can be accessed through :attr:`Job.context` in the callback. Defaults to
+                :obj:`None`.
             name (:obj:`str`, optional): The name of the new job. Defaults to
                 ``callback.__name__``.
             job_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to pass to the
-                ``scheduler.add_job()``.
+                :meth:`apscheduler.schedulers.base.BaseScheduler.add_job()`.
 
         Returns:
-            :class:`telegram.ext.Job`: The new ``Job`` instance that has been added to the job
+            :class:`telegram.ext.Job`: The new :class:`Job` instance that has been added to the job
             queue.
 
         """
@@ -272,7 +275,11 @@ class JobQueue:
         name: str = None,
         job_kwargs: JSONDict = None,
     ) -> 'Job':
-        """Creates a new ``Job`` that runs on a monthly basis and adds it to the queue.
+        """Creates a new :class:`Job` that runs on a monthly basis and adds it to the queue.
+
+        .. versionchanged:: 14.0
+            The ``day_is_strict`` argument was removed. Instead one can now pass -1 to the ``day``
+            parameter to have the job run on the last day of the month.
 
         .. versionchanged:: 14.0
             The ``day_is_strict`` argument was removed. Instead one can now pass -1 to the ``day``
@@ -280,7 +287,7 @@ class JobQueue:
 
         Args:
             callback (:obj:`callable`):  The callback function that should be executed by the new
-                job. Callback signature: ``def callback(update: Update, context: CallbackContext)``
+                job. Callback signature: ``def callback(context: CallbackContext)``
             when (:obj:`datetime.time`): Time of day at which the job should run. If the timezone
                 (``when.tzinfo``) is :obj:`None`, the default timezone of the bot will be used.
             day (:obj:`int`): Defines the day of the month whereby the job would run. It should
@@ -288,14 +295,15 @@ class JobQueue:
                 number, the job will not run in this month. Passing -1 leads to the job running on
                 the last day of the month.
             context (:obj:`object`, optional): Additional data needed for the callback function.
-                Can be accessed through ``job.context`` in the callback. Defaults to :obj:`None`.
+                Can be accessed through :attr:`Job.context` in the callback. Defaults to
+                :obj:`None`.
             name (:obj:`str`, optional): The name of the new job. Defaults to
                 ``callback.__name__``.
             job_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to pass to the
-                ``scheduler.add_job()``.
+                :meth:`apscheduler.schedulers.base.BaseScheduler.add_job()`.
 
         Returns:
-            :class:`telegram.ext.Job`: The new ``Job`` instance that has been added to the job
+            :class:`telegram.ext.Job`: The new :class:`Job` instance that has been added to the job
             queue.
 
         """
@@ -329,7 +337,7 @@ class JobQueue:
         name: str = None,
         job_kwargs: JSONDict = None,
     ) -> 'Job':
-        """Creates a new ``Job`` that runs on a daily basis and adds it to the queue.
+        """Creates a new :class:`Job` that runs on a daily basis and adds it to the queue.
 
         Note:
             For a note about DST, please see the documentation of `APScheduler`_.
@@ -339,20 +347,21 @@ class JobQueue:
 
         Args:
             callback (:obj:`callable`): The callback function that should be executed by the new
-                job. Callback signature: ``def callback(update: Update, context: CallbackContext)``
+                job. Callback signature: ``def callback(context: CallbackContext)``
             time (:obj:`datetime.time`): Time of day at which the job should run. If the timezone
-                (``time.tzinfo``) is :obj:`None`, the default timezone of the bot will be used.
+                (:obj:`time.tzinfo`) is :obj:`None`, the default timezone of the bot will be used.
             days (Tuple[:obj:`int`], optional): Defines on which days of the week the job should
                 run (where ``0-6`` correspond to monday - sunday). Defaults to ``EVERY_DAY``
             context (:obj:`object`, optional): Additional data needed for the callback function.
-                Can be accessed through ``job.context`` in the callback. Defaults to :obj:`None`.
+                Can be accessed through :attr:`Job.context` in the callback. Defaults to
+                :obj:`None`.
             name (:obj:`str`, optional): The name of the new job. Defaults to
                 ``callback.__name__``.
             job_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to pass to the
-                ``scheduler.add_job()``.
+                :meth:`apscheduler.schedulers.base.BaseScheduler.add_job()`.
 
         Returns:
-            :class:`telegram.ext.Job`: The new ``Job`` instance that has been added to the job
+            :class:`telegram.ext.Job`: The new :class:`Job` instance that has been added to the job
             queue.
 
         """
@@ -385,20 +394,21 @@ class JobQueue:
         context: object = None,
         name: str = None,
     ) -> 'Job':
-        """Creates a new customly defined ``Job``.
+        """Creates a new custom defined :class:`Job`.
 
         Args:
             callback (:obj:`callable`): The callback function that should be executed by the new
-                job. Callback signature: ``def callback(update: Update, context: CallbackContext)``
+                job. Callback signature: ``def callback(context: CallbackContext)``
             job_kwargs (:obj:`dict`): Arbitrary keyword arguments. Used as arguments for
-                ``scheduler.add_job``.
+                :meth:`apscheduler.schedulers.base.BaseScheduler.add_job`.
             context (:obj:`object`, optional): Additional data needed for the callback function.
-                Can be accessed through ``job.context`` in the callback. Defaults to ``None``.
+                Can be accessed through :attr:`Job.context` in the callback. Defaults to
+                :obj:`None`.
             name (:obj:`str`, optional): The name of the new job. Defaults to
                 ``callback.__name__``.
 
         Returns:
-            :class:`telegram.ext.Job`: The new ``Job`` instance that has been added to the job
+            :class:`telegram.ext.Job`: The new :class:`Job` instance that has been added to the job
             queue.
 
         """
@@ -421,7 +431,7 @@ class JobQueue:
             self.scheduler.shutdown()
 
     def jobs(self) -> Tuple['Job', ...]:
-        """Returns a tuple of all *scheduled* jobs that are currently in the ``JobQueue``."""
+        """Returns a tuple of all *scheduled* jobs that are currently in the :class:`JobQueue`."""
         return tuple(
             Job._from_aps_job(job)  # pylint: disable=protected-access
             for job in self.scheduler.get_jobs()
@@ -429,7 +439,7 @@ class JobQueue:
 
     def get_jobs_by_name(self, name: str) -> Tuple['Job', ...]:
         """Returns a tuple of all *pending/scheduled* jobs with the given name that are currently
-        in the ``JobQueue``.
+        in the :class:`JobQueue`.
         """
         return tuple(job for job in self.jobs() if job.name == name)
 
@@ -446,7 +456,7 @@ class Job:
         * All attributes and instance methods of :attr:`job` are also directly available as
           attributes/methods of the corresponding :class:`telegram.ext.Job` object.
         * Two instances of :class:`telegram.ext.Job` are considered equal, if their corresponding
-          ``job`` attributes have the same ``id``.
+          :attr:`job` attributes have the same ``id``.
         * If :attr:`job` isn't passed on initialization, it must be set manually afterwards for
           this :class:`telegram.ext.Job` to be useful.
 
@@ -455,9 +465,9 @@ class Job:
 
     Args:
         callback (:obj:`callable`): The callback function that should be executed by the new job.
-            Callback signature: ``def callback(update: Update, context: CallbackContext)``
+            Callback signature: ``def callback(context: CallbackContext)``
         context (:obj:`object`, optional): Additional data needed for the callback function. Can be
-            accessed through ``job.context`` in the callback. Defaults to :obj:`None`.
+            accessed through :attr:`Job.context` in the callback. Defaults to :obj:`None`.
         name (:obj:`str`, optional): The name of the new job. Defaults to ``callback.__name__``.
         job (:class:`apscheduler.job.Job`, optional): The APS Job this job is a wrapper for.
 
@@ -498,7 +508,7 @@ class Job:
         """Executes the callback function independently of the jobs schedule. Also calls
         :meth:`telegram.ext.Dispatcher.update_persistence`.
 
-        .. versionchaged:: 14.0
+        .. versionchanged:: 14.0
             Calls :meth:`telegram.ext.Dispatcher.update_persistence`.
 
         Args:
@@ -531,8 +541,8 @@ class Job:
 
     def schedule_removal(self) -> None:
         """
-        Schedules this job for removal from the ``JobQueue``. It will be removed without executing
+        Schedules this job for removal from the :class:`JobQueue`. It will be removed without
-        its callback function again.
+        executing its callback function again.
         """
         self.job.remove()
         self._removed = True
@@ -559,7 +569,7 @@ class Job:
     def next_t(self) -> Optional[datetime.datetime]:
         """
         :obj:`datetime.datetime`: Datetime for the next job execution.
-            Datetime is localized according to :attr:`tzinfo`.
+            Datetime is localized according to :attr:`datetime.datetime.tzinfo`.
             If job is removed or already ran it equals to :obj:`None`.
         """
         return self.job.next_run_time