Documentation Improvements (#3103, #3121, #3098)

Co-authored-by: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com>
Co-authored-by: David <dsb321mp@gmail.com>
Co-authored-by: Harshil Mehta <37377066+harshil21@users.noreply.github.com>
Co-authored-by: poolitzer <github@poolitzer.eu>
Co-authored-by: Alex <53974096+ExalFabu@users.noreply.github.com>

AUTHORS.rst

@@ -46,6 +46,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Evan Haberecht <https://github.com/habereet>`_
 - `Evgeny Denisov <https://github.com/eIGato>`_
 - `evgfilim1 <https://github.com/evgfilim1>`_
+- `ExalFabu <https://github.com/ExalFabu>`_
 - `franciscod <https://github.com/franciscod>`_
 - `gamgi <https://github.com/gamgi>`_
 - `Gauthamram Ravichandran <https://github.com/GauthamramRavichandran>`_

README.rst

@@ -34,7 +34,7 @@
    :target: https://github.com/python-telegram-bot/python-telegram-bot/
    :alt: Github Actions workflow
 
-.. image:: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg
+.. image:: https://codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg
    :target: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot
    :alt: Code coverage
 
@@ -149,7 +149,7 @@ Resources
 =========
 
 - The `package documentation <https://docs.python-telegram-bot.org/>`_ is the technical reference for ``python-telegram-bot``.
-  It contains descriptions of all available classes, modules, methods and arguments.
+  It contains descriptions of all available classes, modules, methods and arguments as well as the `changelog <https://docs.python-telegram-bot.org/changelog.html>`_.
 - The `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ is home to number of more elaborate introductions of the different features of ``python-telegram-bot`` and other useful resources that go beyond the technical documentation.
 - Our `examples section <https://docs.python-telegram-bot.org/examples.html>`_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``.
   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.

README_RAW.rst

@@ -34,7 +34,7 @@
    :target: https://github.com/python-telegram-bot/python-telegram-bot/
    :alt: Github Actions workflow
 
-.. image:: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg
+.. image:: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot
    :target: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot
    :alt: Code coverage
 
@@ -146,7 +146,7 @@ Resources
 =========
 
 - The `package documentation <https://docs.python-telegram-bot.org/>`_ is the technical reference for ``python-telegram-bot``.
-  It contains descriptions of all available classes, modules, methods and arguments.
+  It contains descriptions of all available classes, modules, methods and arguments as well as the `changelog <https://docs.python-telegram-bot.org/changelog.html>`_.
 - The `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ is home to number of more elaborate introductions of the different features of ``python-telegram-bot`` and other useful resources that go beyond the technical documentation.
 - Our `examples section <https://docs.python-telegram-bot.org/examples.html>`_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``.
   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.

docs/requirements-docs.txt

@@ -1,5 +1,5 @@
-sphinx==5.0.1
+sphinx==5.0.2
 sphinx-pypi-upload
-furo==2022.6.4.1
+furo==2022.6.21
 sphinx-paramlinks==0.5.4
 sphinxcontrib-mermaid==0.7.1

telegram/_bot.py

@@ -1612,7 +1612,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
         changed in the future.
 
         Note:
-            ``thumb`` will be ignored for small files, for which Telegram can easily
+            :paramref:`thumb` will be ignored for small files, for which Telegram can easily
             generate thumb nails. However, this behaviour is undocumented and might be changed
             by Telegram.
 
@@ -3025,7 +3025,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
                 seconds from the current time they are considered to be banned forever. Applied
                 for supergroups and channels only.
                 For timezone naive :obj:`datetime.datetime` objects, the default timezone of the
-                bot will be used.
+                bot will be used, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is
+                used.
             revoke_messages (:obj:`bool`, optional): Pass :obj:`True` to delete all messages from
                 the chat for the user that is being removed. If :obj:`False`, the user will be able
                 to see messages in the group that were sent before the user was removed.
@@ -3373,6 +3374,10 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
         """
         Use this method to edit text and game messages.
 
+        Note:
+            It is currently only possible to edit messages without
+            :attr:`telegram.Message.reply_markup` or with inline keyboards.
+
         Args:
             chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not
                 specified. Unique identifier for the target chat or username of the target channel
@@ -3465,6 +3470,10 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
         """
         Use this method to edit captions of messages.
 
+        Note:
+            It is currently only possible to edit messages without
+            :attr:`telegram.Message.reply_markup` or with inline keyboards
+
         Args:
             chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not
                 specified. Unique identifier for the target chat or username of the target channel
@@ -3553,7 +3562,11 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
         is part of a message album, then it can be edited only to an audio for audio albums, only
         to a document for document albums and to a photo or a video otherwise. When an inline
         message is edited, a new file can't be uploaded; use a previously uploaded file via its
-        ``file_id`` or specify a URL.
+        :attr:`~telegram.File.file_id` or specify a URL.
+
+        Note:
+            It is currently only possible to edit messages without
+            :attr:`telegram.Message.reply_markup` or with inline keyboards
 
         Args:
             media (:class:`telegram.InputMedia`): An object for a new media content
@@ -3629,6 +3642,10 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
         Use this method to edit only the reply markup of messages sent by the bot or via the bot
         (for inline bots).
 
+        Note:
+            It is currently only possible to edit messages without
+            :attr:`telegram.Message.reply_markup` or with inline keyboards
+
         Args:
             chat_id (:obj:`int` | :obj:`str`, optional): Required if inline_message_id is not
                 specified. Unique identifier for the target chat or username of the target channel
@@ -4632,7 +4649,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
                 suggested amounts of tips in the *smallest* units of the currency (integer, **not**
                 float/double). At most 4 suggested tip amounts can be specified. The suggested tip
                 amounts must be positive, passed in a strictly increased order and must not exceed
-                ``max_tip_amount``.
+                :paramref:`max_tip_amount`.
 
                 .. versionadded:: 13.5
             start_parameter (:obj:`str`, optional): Unique deep-linking parameter. If left empty,
@@ -4776,10 +4793,10 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
         api_kwargs: JSONDict = None,
     ) -> bool:
         """
-        If you sent an invoice requesting a shipping address and the parameter ``is_flexible`` was
+        If you sent an invoice requesting a shipping address and the parameter
-        specified, the Bot API will send an :class:`telegram.Update` with a
+        :paramref:`send_invoice.is_flexible` was specified, the Bot API will send an
-        :attr:`telegram.Update.shipping_query` field to the bot. Use this method to reply to
+        :class:`telegram.Update` with a :attr:`telegram.Update.shipping_query` field to the bot.
-        shipping queries.
+        Use this method to reply to shipping queries.
 
         Args:
             shipping_query_id (:obj:`str`): Unique identifier for the query to be answered.
@@ -4999,7 +5016,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
                 days or less than 30 seconds from the current time, they are considered to be
                 restricted forever.
                 For timezone naive :obj:`datetime.datetime` objects, the default timezone of the
-                bot will be used.
+                bot will be used, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is
+                used.
             permissions (:class:`telegram.ChatPermissions`): An object for new user
                 permissions.
 
@@ -5383,7 +5401,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
             expire_date (:obj:`int` | :obj:`datetime.datetime`, optional): Date when the link will
                 expire. Integer input will be interpreted as Unix timestamp.
                 For timezone naive :obj:`datetime.datetime` objects, the default timezone of the
-                bot will be used.
+                bot will be used, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is
+                used.
             member_limit (:obj:`int`, optional): Maximum number of users that can be members of
                 the chat simultaneously after joining the chat via this invite link;
                 1-:tg-const:`telegram.constants.ChatInviteLinkLimit.MEMBER_LIMIT`.
@@ -5393,7 +5412,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
                 .. versionadded:: 13.8
             creates_join_request (:obj:`bool`, optional): :obj:`True`, if users joining the chat
                 via the link need to be approved by chat administrators.
-                If :obj:`True`, ``member_limit`` can't be specified.
+                If :obj:`True`, :paramref:`member_limit` can't be specified.
 
                 .. versionadded:: 13.8
 
@@ -5484,7 +5503,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
             expire_date (:obj:`int` | :obj:`datetime.datetime`, optional): Date when the link will
                 expire.
                 For timezone naive :obj:`datetime.datetime` objects, the default timezone of the
-                bot will be used.
+                bot will be used, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is
+                used.
             member_limit (:obj:`int`, optional): Maximum number of users that can be members of
                 the chat simultaneously after joining the chat via this invite link;
                 1-:tg-const:`telegram.constants.ChatInviteLinkLimit.MEMBER_LIMIT`.
@@ -5494,7 +5514,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
                 .. versionadded:: 13.8
             creates_join_request (:obj:`bool`, optional): :obj:`True`, if users joining the chat
                 via the link need to be approved by chat administrators.
-                If :obj:`True`, ``member_limit`` can't be specified.
+                If :obj:`True`, :paramref:`member_limit` can't be specified.
 
                 .. versionadded:: 13.8
 
@@ -5981,8 +6001,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
         """
         Use this method to add a message to the list of pinned messages in a chat. If the
         chat is not a private chat, the bot must be an administrator in the chat for this to work
-        and must have the ``can_pin_messages`` admin right in a supergroup
+        and must have the :paramref:`~telegram.ChatAdministratorRights.can_pin_messages` admin
-        or :attr:`telegram.ChatMemberAdministrator.can_edit_messages` admin right in a channel.
+        right in a supergroup or :attr:`~telegram.ChatMemberAdministrator.can_edit_messages` admin
+        right in a channel.
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@@ -6046,9 +6067,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
         """
         Use this method to remove a message from the list of pinned messages in a chat. If the
         chat is not a private chat, the bot must be an administrator in the chat for this to work
-        and must have the ``can_pin_messages`` admin right in a
+        and must have the :paramref:`~telegram.ChatAdministratorRights.can_pin_messages` admin
-        supergroup or :attr:`telegram.ChatMemberAdministrator.can_edit_messages` admin right in a
+        right in a supergroup or :attr:`~telegram.ChatMemberAdministrator.can_edit_messages` admin
-        channel.
+        right in a channel.
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@@ -6108,9 +6129,9 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
         """
         Use this method to clear the list of pinned messages in a chat. If the
         chat is not a private chat, the bot must be an administrator in the chat for this
-        to work and must have the ``can_pin_messages`` admin right in a
+        to work and must have the :paramref:`~telegram.ChatAdministratorRights.can_pin_messages`
-        supergroup or :attr:`telegram.ChatMemberAdministrator.can_edit_messages` admin right in a
+        admin right in a supergroup or :attr:`~telegram.ChatMemberAdministrator.can_edit_messages`
-        channel.
+        admin right in a channel.
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@@ -6804,7 +6825,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
                 more than 600 seconds in the future. Can't be used together with
                 :paramref:`open_period`.
                 For timezone naive :obj:`datetime.datetime` objects, the default timezone of the
-                bot will be used.
+                bot will be used, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is
+                used.
             is_closed (:obj:`bool`, optional): Pass :obj:`True`, if the poll needs to be
                 immediately closed. This can be useful for poll preview.
             disable_notification (:obj:`bool`, optional): Sends the message silently. Users will

telegram/_inline/inlinekeyboardbutton.py

@@ -18,7 +18,7 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram InlineKeyboardButton."""
 
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Any, Optional, Union
 
 from telegram._games.callbackgame import CallbackGame
 from telegram._loginurl import LoginUrl
@@ -163,7 +163,7 @@ class InlineKeyboardButton(TelegramObject):
         self,
         text: str,
         url: str = None,
-        callback_data: object = None,
+        callback_data: Union[str, object] = None,
         switch_inline_query: str = None,
         switch_inline_query_current_chat: str = None,
         callback_game: CallbackGame = None,
@@ -214,7 +214,7 @@ class InlineKeyboardButton(TelegramObject):
 
         return cls(**data)
 
-    def update_callback_data(self, callback_data: object) -> None:
+    def update_callback_data(self, callback_data: Union[str, object]) -> None:
         """
         Sets :attr:`callback_data` to the passed object. Intended to be used by
         :class:`telegram.ext.CallbackDataCache`.

telegram/ext/_application.py

@@ -359,7 +359,8 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AbstractAsyncContextManager)
 
         * :attr:`bot` by calling :meth:`telegram.Bot.shutdown`
         * :attr:`updater` by calling :meth:`telegram.ext.Updater.shutdown`
-        * :attr:`persistence` by calling :meth:`update_persistence` and :meth`persistence.flush`
+        * :attr:`persistence` by calling :meth:`update_persistence` and
+          :meth:`BasePersistence.flush`
 
         .. seealso::
             :meth:`initialize`

telegram/ext/_callbackdatacache.py

@@ -369,7 +369,8 @@ class CallbackDataCache:
             time_cutoff (:obj:`float` | :obj:`datetime.datetime`, optional): Pass a UNIX timestamp
                 or a :obj:`datetime.datetime` to clear only entries which are older.
                 For timezone naive :obj:`datetime.datetime` objects, the default timezone of the
-                bot will be used.
+                bot will be used, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is
+                used.
 
         """
         self.__clear(self._keyboard_data, time_cutoff=time_cutoff)

telegram/ext/_jobqueue.py

@@ -148,11 +148,13 @@ class JobQueue:
                   job should run.
                 * :obj:`datetime.datetime` will be interpreted as a specific date and time at
                   which the job should run. If the timezone (:attr:`datetime.datetime.tzinfo`) is
-                  :obj:`None`, the default timezone of the bot will be used.
+                  :obj:`None`, the default timezone of the bot will be used, which is UTC unless
+                  :attr:`telegram.ext.Defaults.tzinfo` is 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 (:attr:`datetime.time.tzinfo`) is :obj:`None`, the
-                  default timezone of the bot will be used.
+                  default timezone of the bot will be used, which is UTC unless
+                  :attr:`telegram.ext.Defaults.tzinfo` is used.
 
             chat_id (:obj:`int`, optional): Chat id of the chat associated with this job. If
                 passed, the corresponding :attr:`~telegram.ext.CallbackContext.chat_data` will
@@ -246,7 +248,8 @@ class JobQueue:
                 * :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 (:attr:`datetime.time.tzinfo`) is :obj:`None`, the
-                  default timezone of the bot will be used.
+                  default timezone of the bot will be used, which is UTC unless
+                  :attr:`telegram.ext.Defaults.tzinfo` is used.
 
                 Defaults to :paramref:`interval`
             last (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta` |                        \
@@ -256,7 +259,7 @@ class JobQueue:
 
                 If :paramref:`last` is :obj:`datetime.datetime` or :obj:`datetime.time` type
                 and ``last.tzinfo`` is :obj:`None`, the default timezone of the bot will be
-                assumed.
+                assumed, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is used.
 
                 Defaults to :obj:`None`.
             data (:obj:`object`, optional): Additional data needed for the callback function.
@@ -339,7 +342,8 @@ class JobQueue:
                     async 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.
+                (``when.tzinfo``) is :obj:`None`, the default timezone of the bot will be used,
+                which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is used.
             day (:obj:`int`): Defines the day of the month whereby the job would run. It should
                 be within the range of ``1`` and ``31``, inclusive. If a month has fewer days than
                 this number, the job will not run in this month. Passing ``-1`` leads to the job
@@ -419,7 +423,7 @@ class JobQueue:
 
             time (:obj:`datetime.time`): Time of day at which the job should run. If the timezone
                 (:obj:`datetime.time.tzinfo`) is :obj:`None`, the default timezone of the bot will
-                be used.
+                be used, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is used.
             days (Tuple[:obj:`int`], optional): Defines on which days of the week the job should
                 run (where ``0-6`` correspond to sunday - saturday). By default, the job will run
                 every day.
@@ -591,6 +595,7 @@ class Job:
           this :class:`telegram.ext.Job` to be useful.
 
     .. versionchanged:: 20.0
+
        * Removed argument and attribute ``job_queue``.
        * Renamed ``Job.context`` to :attr:`Job.data`.