Documentation Improvements (#3565, #3600)

Co-authored-by: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com>
Co-authored-by: poolitzer <github@poolitzer.eu>
Co-authored-by: Louis Wang <beiluonever@users.noreply.github.com>

CHANGES.rst

@@ -2108,7 +2108,7 @@ Changes
 - Lots of small improvements to our tests and documentation.
 
 
-.. _`see docs`: https://docs.python-telegram-bot.org/en/stable/telegram.ext.dispatcher.html#telegram.ext.Dispatcher.add_handler
+.. _`see docs`: https://docs.python-telegram-bot.org/en/v13.11/telegram.ext.dispatcher.html?highlight=Dispatcher.add_handler#telegram.ext.Dispatcher.add_handler
 .. _`#777`: https://github.com/python-telegram-bot/python-telegram-bot/pull/777
 .. _`#806`: https://github.com/python-telegram-bot/python-telegram-bot/pull/806
 .. _`#766`: https://github.com/python-telegram-bot/python-telegram-bot/pull/766

docs/requirements-docs.txt

@@ -3,5 +3,5 @@ sphinx-pypi-upload
 furo==2023.3.23
 git+https://github.com/harshil21/furo-sphinx-search@01efc7be422d7dc02390aab9be68d6f5ce1a5618#egg=furo-sphinx-search
 sphinx-paramlinks==0.5.4
-sphinxcontrib-mermaid==0.8
+sphinxcontrib-mermaid==0.8.1
 sphinx-copybutton==0.5.1

examples/timerbot.py

@@ -18,8 +18,8 @@ Press Ctrl-C on the command line or send a signal to the process to stop the
 bot.
 
 Note:
-To use arbitrary callback data, you must install ptb via
-`pip install python-telegram-bot[callback-data]`
+To use the JobQueue, you must install PTB via
+`pip install python-telegram-bot[job-queue]`
 """
 
 import logging

telegram/_bot.py

@@ -7018,6 +7018,11 @@ CUSTOM_EMOJI_IDENTIFIER_LIMIT` custom emoji identifiers can be specified.
                 :tg-const:`telegram.constants.BotCommandLimit.MAX_COMMAND_NUMBER` commands can be
                 specified.
 
+                Note:
+                    If you pass in a sequence of :obj:`tuple`, the order of elements in each
+                    :obj:`tuple` must correspond to the order of positional arguments to create a
+                    :class:`BotCommand` instance.
+
                 .. versionchanged:: 20.0
                     |sequenceargs|
             scope (:class:`telegram.BotCommandScope`, optional): An object,

telegram/_keyboardbuttonrequest.py

@@ -34,6 +34,10 @@ class KeyboardButtonRequestUser(TelegramObject):
     Objects of this class are comparable in terms of equality. Two objects of this class are
     considered equal, if their :attr:`request_id` is equal.
 
+    .. seealso::
+        `Telegram Docs on requesting users \
+        <https://core.telegram.org/bots/features#chat-and-user-selection>`_
+
     .. versionadded:: 20.1
 
     Args:
@@ -87,6 +91,10 @@ class KeyboardButtonRequestChat(TelegramObject):
     Objects of this class are comparable in terms of equality. Two objects of this class are
     considered equal, if their :attr:`request_id` is equal.
 
+    .. seealso::
+        `Telegram Docs on requesting chats \
+        <https://core.telegram.org/bots/features#chat-and-user-selection>`_
+
     .. versionadded:: 20.1
 
     Args:

telegram/ext/_application.py

@@ -953,7 +953,7 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AsyncContextManager["Applica
         Args:
             coroutine (:term:`awaitable`): The awaitable to run as task.
 
-                .. versionchanged:: 20.2
+                .. versionchanged:: NEXT.VERSION
                     Accepts :class:`asyncio.Future` and generator-based coroutine functions.
             update (:obj:`object`, optional): If set, will be passed to :meth:`process_error`
                 as additional information for the error handlers. Moreover, the corresponding

telegram/ext/_callbackcontext.py

@@ -306,7 +306,7 @@ class CallbackContext(Generic[BT, UD, CD, BD]):
 
                 .. versionadded:: 20.0
 
-                .. versionchanged:: 20.2
+                .. versionchanged:: NEXT.VERSION
                     Accepts :class:`asyncio.Future` and generator-based coroutine functions.
         Returns:
             :class:`telegram.ext.CallbackContext`

telegram/ext/_conversationhandler.py

@@ -259,7 +259,7 @@ class ConversationHandler(BaseHandler[Update, CCT]):
             when :attr:`per_message`, :attr:`per_chat`, :attr:`per_user` are all :obj:`False`.
 
     Attributes:
-        block (:obj:`bool`): Determines whether the callback will run in a blocking way.. Always
+        block (:obj:`bool`): Determines whether the callback will run in a blocking way. Always
             :obj:`True` since conversation handlers handle any non-blocking callbacks internally.
 
     """

telegram/warnings.py

@@ -47,7 +47,8 @@ class PTBRuntimeWarning(PTBUserWarning, RuntimeWarning):
 
 
 # https://www.python.org/dev/peps/pep-0565/ recommends using a custom warning class derived from
-# DeprecationWarning. We also subclass from TGUserWarning so users can easily 'switch off' warnings
+# DeprecationWarning. We also subclass from PTBUserWarning so users can easily 'switch off'
+# warnings
 class PTBDeprecationWarning(PTBUserWarning, DeprecationWarning):
     """
     Custom warning class for deprecations in this library.