Doc Fixes (#2404)

* Improve some badges for PTB-Raw

* doc fix for add_error_handler

* Some rendering

* Bump sphinx dependency

* Change signature annotation setting

* fix: chat_id can be string, message_id only int

* feat: add RTD link to documentation

* improving sender chat docstring (#2412)

* fix: improving sender chat docstring

also adding a note to a weird edge case

* fix: words being hard

* Add note on donations

* typo

* typo in User.get_profile_pictures docstrings

* Fix: meth, not attr for meth, not attr

* filters + inlinequery doc fix

* Bump versions, update RTD config file

* Try fix build

* Revert "fix: chat_id can be string, message_id only int"

This reverts commit ba04e5aa

* Add Starry & Harshil to credits

Co-authored-by: poolitzer <25934244+Poolitzer@users.noreply.github.com>
Co-authored-by: Harshil <ilovebhagwan@gmail.com>

.github/CONTRIBUTING.rst

@@ -50,6 +50,8 @@ Instructions for making a code change
 
 The central development branch is ``master``, which should be clean and ready for release at any time. In general, all changes should be done as feature branches based off of ``master``.
 
+If you want to do solely documentation changes, base them and PR to the branch ``doc-fixes``. This branch also has its own `RTD build`_.
+
 Here's how to make a one-off code change.
 
 1. **Choose a descriptive branch name.** It should be lowercase, hyphen-separated, and a noun describing the change (so, ``fuzzy-rules``, but not ``implement-fuzzy-rules``). Also, it shouldn't start with ``hotfix`` or ``release``.
@@ -250,3 +252,4 @@ break the API classes. For example:
 .. _`here`: https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html
 .. _`Black`: https://black.readthedocs.io/en/stable/index.html
 .. _`popular editors`: https://black.readthedocs.io/en/stable/editor_integration.html
+.. _`RTD build`: https://python-telegram-bot.readthedocs.io/en/doc-fixes

.readthedocs.yml

@@ -1,10 +1,22 @@
-# syntax: https://docs.readthedocs.io/en/latest/yaml-config.html
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/source/conf.py
+
+# Optionally build your docs in additional formats such as PDF
 formats:
-    - pdf
+   - pdf
 
+# Optionally set the version of Python and requirements required to build your docs
 python:
-   setup_py_install: true
    version: 3
-
+   install:
-requirements_file: docs/requirements-docs.txt
+     - method: pip
+       path: .
+     - requirements: docs/requirements-docs.txt

AUTHORS.rst

@@ -2,12 +2,20 @@ Credits
 =======
 
 ``python-telegram-bot`` was originally created by
-`Leandro Toledo <https://github.com/leandrotoledo>`_ and is now maintained by `Hinrich Mahler <https://github.com/Bibo-Joshi>`_.
+`Leandro Toledo <https://github.com/leandrotoledo>`_.
+The current development team includes
+
+- `Hinrich Mahler <https://github.com/Bibo-Joshi>`_ (maintainer)
+- `Poolitzer <https://github.com/Poolitzer>`_ (community liaison)
+- `Shivam <https://github.com/Starry69>`_
+- `Harshil <https://github.com/harshil21>`_
+
 Emeritus maintainers include
 `Jannes Höke <https://github.com/jh0ker>`_ (`@jh0ker <https://t.me/jh0ker>`_ on Telegram),
 `Noam Meltzer <https://github.com/tsnoam>`_, `Pieter Schutz <https://github.com/eldinnie>`_ and `Jasmin Bom <https://github.com/jsmnbom>`_.
 
-The maintainers are actively supported by `Poolitzer <https://github.com/Poolitzer>`_ in terms of development and community liaison.
+Vendored packages
+-----------------
 
 We're vendoring urllib3 as part of ``python-telegram-bot`` which is distributed under the MIT
 license. For more info, full credits & license terms, the sources can be found here:

README.rst

@@ -230,6 +230,11 @@ Contributing
 
 Contributions of all sizes are welcome. Please review our `contribution guidelines <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst>`_ to get started. You can also help by `reporting bugs <https://github.com/python-telegram-bot/python-telegram-bot/issues/new>`_.
 
+========
+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.
+
 =======
 License
 =======

README_RAW.rst

@@ -212,6 +212,11 @@ Contributing
 
 Contributions of all sizes are welcome. Please review our `contribution guidelines <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst>`_ to get started. You can also help by `reporting bugs <https://github.com/python-telegram-bot/python-telegram-bot/issues/new>`_.
 
+========
+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.
+
 =======
 License
 =======

docs/requirements-docs.txt

@@ -1,3 +1,3 @@
-sphinx>=1.7.9
+sphinx==3.5.2
-sphinx_rtd_theme
+sphinx_rtd_theme==0.5.1
 sphinx-pypi-upload

docs/source/conf.py

@@ -24,7 +24,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = '1.7.9'
+needs_sphinx = '3.5.2'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -35,7 +35,7 @@ extensions = [
 ]
 # Don't show type hints in the signature - that just makes it hardly readable
 # and we document the types anyway
-autodoc_typehints = 'description'
+autodoc_typehints = 'none'
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

telegram/bot.py

@@ -1574,7 +1574,7 @@ class Bot(TelegramObject):
     ) -> Union[Message, bool]:
         """Use this method to edit live location messages sent by the bot or via the bot
         (for inline bots). A location can be edited until its :attr:`live_period` expires or
-        editing is explicitly disabled by a call to :attr:`stop_message_live_location`.
+        editing is explicitly disabled by a call to :meth:`stop_message_live_location`.
 
         Note:
             You can either supply a :obj:`latitude` and :obj:`longitude` or a :obj:`location`.
@@ -2200,7 +2200,7 @@ class Bot(TelegramObject):
         """
         Use this method to get basic info about a file and prepare it for downloading. For the
         moment, bots can download files of up to 20MB in size. The file can then be downloaded
-        with :attr:`telegram.File.download`. It is guaranteed that the link will be
+        with :meth:`telegram.File.download`. It is guaranteed that the link will be
         valid for at least 1 hour. When the link expires, a new one can be requested by
         calling get_file again.
 
@@ -3074,7 +3074,7 @@ class Bot(TelegramObject):
         """Use this method to set a new group sticker set for a supergroup.
         The bot must be an administrator in the chat for this to work and must have the appropriate
         admin rights. Use the field :attr:`telegram.Chat.can_set_sticker_set` optionally returned
-        in :attr:`get_chat` requests to check if the bot can use this method.
+        in :meth:`get_chat` requests to check if the bot can use this method.
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@@ -3106,7 +3106,7 @@ class Bot(TelegramObject):
         """Use this method to delete a group sticker set from a supergroup. The bot must be an
         administrator in the chat for this to work and must have the appropriate admin rights.
         Use the field :attr:`telegram.Chat.can_set_sticker_set` optionally returned in
-        :attr:`get_chat` requests to check if the bot can use this method.
+        :meth:`get_chat` requests to check if the bot can use this method.
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@@ -3541,7 +3541,7 @@ class Bot(TelegramObject):
         :obj:`True` for all boolean parameters to lift restrictions from a user.
 
         Note:
-            Since Bot API 4.4, :attr:`restrict_chat_member` takes the new user permissions in a
+            Since Bot API 4.4, :meth:`restrict_chat_member` takes the new user permissions in a
             single argument of type :class:`telegram.ChatPermissions`. The old way of passing
             parameters will not keep working forever.
 
@@ -4261,7 +4261,7 @@ class Bot(TelegramObject):
     ) -> File:
         """
         Use this method to upload a .png file with a sticker for later use in
-        :attr:`create_new_sticker_set` and :attr:`add_sticker_to_set` methods (can be used multiple
+        :meth:`create_new_sticker_set` and :meth:`add_sticker_to_set` methods (can be used multiple
         times).
 
         Note:
@@ -5061,107 +5061,107 @@ class Bot(TelegramObject):
 
     # camelCase aliases
     getMe = get_me
-    """Alias for :attr:`get_me`"""
+    """Alias for :meth:`get_me`"""
     sendMessage = send_message
-    """Alias for :attr:`send_message`"""
+    """Alias for :meth:`send_message`"""
     deleteMessage = delete_message
-    """Alias for :attr:`delete_message`"""
+    """Alias for :meth:`delete_message`"""
     forwardMessage = forward_message
-    """Alias for :attr:`forward_message`"""
+    """Alias for :meth:`forward_message`"""
     sendPhoto = send_photo
-    """Alias for :attr:`send_photo`"""
+    """Alias for :meth:`send_photo`"""
     sendAudio = send_audio
-    """Alias for :attr:`send_audio`"""
+    """Alias for :meth:`send_audio`"""
     sendDocument = send_document
-    """Alias for :attr:`send_document`"""
+    """Alias for :meth:`send_document`"""
     sendSticker = send_sticker
-    """Alias for :attr:`send_sticker`"""
+    """Alias for :meth:`send_sticker`"""
     sendVideo = send_video
-    """Alias for :attr:`send_video`"""
+    """Alias for :meth:`send_video`"""
     sendAnimation = send_animation
-    """Alias for :attr:`send_animation`"""
+    """Alias for :meth:`send_animation`"""
     sendVoice = send_voice
-    """Alias for :attr:`send_voice`"""
+    """Alias for :meth:`send_voice`"""
     sendVideoNote = send_video_note
-    """Alias for :attr:`send_video_note`"""
+    """Alias for :meth:`send_video_note`"""
     sendMediaGroup = send_media_group
-    """Alias for :attr:`send_media_group`"""
+    """Alias for :meth:`send_media_group`"""
     sendLocation = send_location
-    """Alias for :attr:`send_location`"""
+    """Alias for :meth:`send_location`"""
     editMessageLiveLocation = edit_message_live_location
-    """Alias for :attr:`edit_message_live_location`"""
+    """Alias for :meth:`edit_message_live_location`"""
     stopMessageLiveLocation = stop_message_live_location
-    """Alias for :attr:`stop_message_live_location`"""
+    """Alias for :meth:`stop_message_live_location`"""
     sendVenue = send_venue
-    """Alias for :attr:`send_venue`"""
+    """Alias for :meth:`send_venue`"""
     sendContact = send_contact
-    """Alias for :attr:`send_contact`"""
+    """Alias for :meth:`send_contact`"""
     sendGame = send_game
-    """Alias for :attr:`send_game`"""
+    """Alias for :meth:`send_game`"""
     sendChatAction = send_chat_action
-    """Alias for :attr:`send_chat_action`"""
+    """Alias for :meth:`send_chat_action`"""
     answerInlineQuery = answer_inline_query
-    """Alias for :attr:`answer_inline_query`"""
+    """Alias for :meth:`answer_inline_query`"""
     getUserProfilePhotos = get_user_profile_photos
-    """Alias for :attr:`get_user_profile_photos`"""
+    """Alias for :meth:`get_user_profile_photos`"""
     getFile = get_file
-    """Alias for :attr:`get_file`"""
+    """Alias for :meth:`get_file`"""
     kickChatMember = kick_chat_member
-    """Alias for :attr:`kick_chat_member`"""
+    """Alias for :meth:`kick_chat_member`"""
     unbanChatMember = unban_chat_member
-    """Alias for :attr:`unban_chat_member`"""
+    """Alias for :meth:`unban_chat_member`"""
     answerCallbackQuery = answer_callback_query
-    """Alias for :attr:`answer_callback_query`"""
+    """Alias for :meth:`answer_callback_query`"""
     editMessageText = edit_message_text
-    """Alias for :attr:`edit_message_text`"""
+    """Alias for :meth:`edit_message_text`"""
     editMessageCaption = edit_message_caption
-    """Alias for :attr:`edit_message_caption`"""
+    """Alias for :meth:`edit_message_caption`"""
     editMessageMedia = edit_message_media
-    """Alias for :attr:`edit_message_media`"""
+    """Alias for :meth:`edit_message_media`"""
     editMessageReplyMarkup = edit_message_reply_markup
-    """Alias for :attr:`edit_message_reply_markup`"""
+    """Alias for :meth:`edit_message_reply_markup`"""
     getUpdates = get_updates
-    """Alias for :attr:`get_updates`"""
+    """Alias for :meth:`get_updates`"""
     setWebhook = set_webhook
-    """Alias for :attr:`set_webhook`"""
+    """Alias for :meth:`set_webhook`"""
     deleteWebhook = delete_webhook
-    """Alias for :attr:`delete_webhook`"""
+    """Alias for :meth:`delete_webhook`"""
     leaveChat = leave_chat
-    """Alias for :attr:`leave_chat`"""
+    """Alias for :meth:`leave_chat`"""
     getChat = get_chat
-    """Alias for :attr:`get_chat`"""
+    """Alias for :meth:`get_chat`"""
     getChatAdministrators = get_chat_administrators
-    """Alias for :attr:`get_chat_administrators`"""
+    """Alias for :meth:`get_chat_administrators`"""
     getChatMember = get_chat_member
-    """Alias for :attr:`get_chat_member`"""
+    """Alias for :meth:`get_chat_member`"""
     setChatStickerSet = set_chat_sticker_set
-    """Alias for :attr:`set_chat_sticker_set`"""
+    """Alias for :meth:`set_chat_sticker_set`"""
     deleteChatStickerSet = delete_chat_sticker_set
-    """Alias for :attr:`delete_chat_sticker_set`"""
+    """Alias for :meth:`delete_chat_sticker_set`"""
     getChatMembersCount = get_chat_members_count
-    """Alias for :attr:`get_chat_members_count`"""
+    """Alias for :meth:`get_chat_members_count`"""
     getWebhookInfo = get_webhook_info
-    """Alias for :attr:`get_webhook_info`"""
+    """Alias for :meth:`get_webhook_info`"""
     setGameScore = set_game_score
-    """Alias for :attr:`set_game_score`"""
+    """Alias for :meth:`set_game_score`"""
     getGameHighScores = get_game_high_scores
-    """Alias for :attr:`get_game_high_scores`"""
+    """Alias for :meth:`get_game_high_scores`"""
     sendInvoice = send_invoice
-    """Alias for :attr:`send_invoice`"""
+    """Alias for :meth:`send_invoice`"""
     answerShippingQuery = answer_shipping_query
-    """Alias for :attr:`answer_shipping_query`"""
+    """Alias for :meth:`answer_shipping_query`"""
     answerPreCheckoutQuery = answer_pre_checkout_query
-    """Alias for :attr:`answer_pre_checkout_query`"""
+    """Alias for :meth:`answer_pre_checkout_query`"""
     restrictChatMember = restrict_chat_member
-    """Alias for :attr:`restrict_chat_member`"""
+    """Alias for :meth:`restrict_chat_member`"""
     promoteChatMember = promote_chat_member
-    """Alias for :attr:`promote_chat_member`"""
+    """Alias for :meth:`promote_chat_member`"""
     setChatPermissions = set_chat_permissions
-    """Alias for :attr:`set_chat_permissions`"""
+    """Alias for :meth:`set_chat_permissions`"""
     setChatAdministratorCustomTitle = set_chat_administrator_custom_title
-    """Alias for :attr:`set_chat_administrator_custom_title`"""
+    """Alias for :meth:`set_chat_administrator_custom_title`"""
     exportChatInviteLink = export_chat_invite_link
-    """Alias for :attr:`export_chat_invite_link`"""
+    """Alias for :meth:`export_chat_invite_link`"""
     createChatInviteLink = create_chat_invite_link
     """Alias for :attr:`create_chat_invite_link`"""
     editChatInviteLink = edit_chat_invite_link
@@ -5169,46 +5169,46 @@ class Bot(TelegramObject):
     revokeChatInviteLink = revoke_chat_invite_link
     """Alias for :attr:`revoke_chat_invite_link`"""
     setChatPhoto = set_chat_photo
-    """Alias for :attr:`set_chat_photo`"""
+    """Alias for :meth:`set_chat_photo`"""
     deleteChatPhoto = delete_chat_photo
-    """Alias for :attr:`delete_chat_photo`"""
+    """Alias for :meth:`delete_chat_photo`"""
     setChatTitle = set_chat_title
-    """Alias for :attr:`set_chat_title`"""
+    """Alias for :meth:`set_chat_title`"""
     setChatDescription = set_chat_description
-    """Alias for :attr:`set_chat_description`"""
+    """Alias for :meth:`set_chat_description`"""
     pinChatMessage = pin_chat_message
-    """Alias for :attr:`pin_chat_message`"""
+    """Alias for :meth:`pin_chat_message`"""
     unpinChatMessage = unpin_chat_message
-    """Alias for :attr:`unpin_chat_message`"""
+    """Alias for :meth:`unpin_chat_message`"""
     unpinAllChatMessages = unpin_all_chat_messages
-    """Alias for :attr:`unpin_all_chat_messages`"""
+    """Alias for :meth:`unpin_all_chat_messages`"""
     getStickerSet = get_sticker_set
-    """Alias for :attr:`get_sticker_set`"""
+    """Alias for :meth:`get_sticker_set`"""
     uploadStickerFile = upload_sticker_file
-    """Alias for :attr:`upload_sticker_file`"""
+    """Alias for :meth:`upload_sticker_file`"""
     createNewStickerSet = create_new_sticker_set
-    """Alias for :attr:`create_new_sticker_set`"""
+    """Alias for :meth:`create_new_sticker_set`"""
     addStickerToSet = add_sticker_to_set
-    """Alias for :attr:`add_sticker_to_set`"""
+    """Alias for :meth:`add_sticker_to_set`"""
     setStickerPositionInSet = set_sticker_position_in_set
-    """Alias for :attr:`set_sticker_position_in_set`"""
+    """Alias for :meth:`set_sticker_position_in_set`"""
     deleteStickerFromSet = delete_sticker_from_set
-    """Alias for :attr:`delete_sticker_from_set`"""
+    """Alias for :meth:`delete_sticker_from_set`"""
     setStickerSetThumb = set_sticker_set_thumb
-    """Alias for :attr:`set_sticker_set_thumb`"""
+    """Alias for :meth:`set_sticker_set_thumb`"""
     setPassportDataErrors = set_passport_data_errors
-    """Alias for :attr:`set_passport_data_errors`"""
+    """Alias for :meth:`set_passport_data_errors`"""
     sendPoll = send_poll
-    """Alias for :attr:`send_poll`"""
+    """Alias for :meth:`send_poll`"""
     stopPoll = stop_poll
-    """Alias for :attr:`stop_poll`"""
+    """Alias for :meth:`stop_poll`"""
     sendDice = send_dice
-    """Alias for :attr:`send_dice`"""
+    """Alias for :meth:`send_dice`"""
     getMyCommands = get_my_commands
-    """Alias for :attr:`get_my_commands`"""
+    """Alias for :meth:`get_my_commands`"""
     setMyCommands = set_my_commands
-    """Alias for :attr:`set_my_commands`"""
+    """Alias for :meth:`set_my_commands`"""
     logOut = log_out
-    """Alias for :attr:`log_out`"""
+    """Alias for :meth:`log_out`"""
     copyMessage = copy_message
-    """Alias for :attr:`copy_message`"""
+    """Alias for :meth:`copy_message`"""

telegram/ext/filters.py

@@ -1117,8 +1117,8 @@ officedocument.wordprocessingml.document")``.
         left_chat_member: Messages that contain
             :attr:`telegram.Message.left_chat_member`.
         migrate: Messages that contain
-            :attr:`telegram.Message.migrate_from_chat_id` or
+            :attr:`telegram.Message.migrate_to_chat_id` or
-            :attr: `telegram.Message.migrate_from_chat_id`.
+            :attr:`telegram.Message.migrate_from_chat_id`.
         new_chat_members: Messages that contain
             :attr:`telegram.Message.new_chat_members`.
         new_chat_photo: Messages that contain
@@ -1738,16 +1738,22 @@ officedocument.wordprocessingml.document")``.
         username.
 
         Examples:
-            * To filter for messages forwarded from a channel with ID ``-1234``, use
+            * To filter for messages forwarded to a discussion group from a channel with ID
-              ``MessageHandler(Filters.sender_chat(-1234), callback_method)``.
+              ``-1234``, use ``MessageHandler(Filters.sender_chat(-1234), callback_method)``.
             * To filter for messages of anonymous admins in a super group with username
               ``@anonymous``, use
               ``MessageHandler(Filters.sender_chat(username='anonymous'), callback_method)``.
-            * To filter for messages forwarded from *any* channel, use
+            * To filter for messages forwarded to a discussion group from *any* channel, use
               ``MessageHandler(Filters.sender_chat.channel, callback_method)``.
             * To filter for messages of anonymous admins in *any* super group, use
               ``MessageHandler(Filters.sender_chat.super_group, callback_method)``.
 
+        Note:
+            Remember, ``sender_chat`` is also set for messages in a channel as the channel itself,
+            so when your bot is an admin in a channel and the linked discussion group, you would
+            receive the message twice (once from inside the channel, once inside the discussion
+            group).
+
         Warning:
             :attr:`chat_ids` will return a *copy* of the saved chat ids as :class:`frozenset`. This
             is to ensure thread safety. To add/remove a chat, you should use :meth:`add_usernames`,

telegram/inline/inlinequery.py

@@ -125,7 +125,7 @@ class InlineQuery(TelegramObject):
                 Defaults to :obj:`False`.
 
         Raises:
-            TypeError: If both :attr:`current_offset` and attr:`auto_pagination` are supplied.
+            TypeError: If both :attr:`current_offset` and :attr:`auto_pagination` are supplied.
         """
         if current_offset and auto_pagination:
             # We raise TypeError instead of ValueError for backwards compatibility with versions

telegram/user.py

@@ -161,7 +161,7 @@ class User(TelegramObject):
         """
         Shortcut for::
 
-            bot.send_message(update.effective_user.id, *args, **kwargs)
+            bot.get_user_profile_photos(update.effective_user.id, *args, **kwargs)
 
         For the documentation of the arguments, please see
         :meth:`telegram.Bot.get_user_profile_photos`.