From 4ddc36c625917848c43df39e835b82bc122416c4 Mon Sep 17 00:00:00 2001 From: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com> Date: Sat, 25 Mar 2023 12:48:34 +0100 Subject: [PATCH] Documentation Improvements (#3565, #3600) Co-authored-by: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com> Co-authored-by: poolitzer Co-authored-by: Louis Wang --- CHANGES.rst | 2 +- docs/requirements-docs.txt | 2 +- examples/timerbot.py | 4 ++-- telegram/_bot.py | 5 +++++ telegram/_keyboardbuttonrequest.py | 8 ++++++++ telegram/ext/_application.py | 2 +- telegram/ext/_callbackcontext.py | 2 +- telegram/ext/_conversationhandler.py | 2 +- telegram/warnings.py | 3 ++- 9 files changed, 22 insertions(+), 8 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index cf88654b3..8c61e6b85 100644 --- a/CHANGES.rst +++ b/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 diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt index d4310c64b..a35ed54d4 100644 --- a/docs/requirements-docs.txt +++ b/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 diff --git a/examples/timerbot.py b/examples/timerbot.py index 29f45caaf..9c49b5588 100644 --- a/examples/timerbot.py +++ b/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 diff --git a/telegram/_bot.py b/telegram/_bot.py index c617a051f..a61f21ec7 100644 --- a/telegram/_bot.py +++ b/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, diff --git a/telegram/_keyboardbuttonrequest.py b/telegram/_keyboardbuttonrequest.py index 70c015ba7..7df40b02f 100644 --- a/telegram/_keyboardbuttonrequest.py +++ b/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 \ + `_ + .. 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 \ + `_ + .. versionadded:: 20.1 Args: diff --git a/telegram/ext/_application.py b/telegram/ext/_application.py index ddb9c0d4e..52f706619 100644 --- a/telegram/ext/_application.py +++ b/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 diff --git a/telegram/ext/_callbackcontext.py b/telegram/ext/_callbackcontext.py index b4b4f1b56..d344ce9b9 100644 --- a/telegram/ext/_callbackcontext.py +++ b/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` diff --git a/telegram/ext/_conversationhandler.py b/telegram/ext/_conversationhandler.py index aa36868e9..ef2f4a474 100644 --- a/telegram/ext/_conversationhandler.py +++ b/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. """ diff --git a/telegram/warnings.py b/telegram/warnings.py index d62193006..8fef6a6c3 100644 --- a/telegram/warnings.py +++ b/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.