Documentation Improvements

README.rst

@@ -136,8 +136,8 @@ Optional Dependencies
 PTB can be installed with optional dependencies:
 
 * ``pip install python-telegram-bot[passport]`` installs the `cryptography>=3.0 <https://cryptography.io/en/stable>`_ library. Use this, if you want to use Telegram Passport related functionality.
-* ``pip install python-telegram-bot[socks]`` installs ``httpx[socks]``. Use this, if you want to work behind a Socks5 server.
-* ``pip install python-telegram-bot[rate-limiter]`` installs ``aiolimiter~=1.0.0``. Use this, if you want to use ``telegram.ext.AIORateLimiter``.
+* ``pip install python-telegram-bot[socks]`` installs `httpx[socks] <https://www.python-httpx.org/#dependencies>`_. Use this, if you want to work behind a Socks5 server.
+* ``pip install python-telegram-bot[rate-limiter]`` installs `aiolimiter~=1.0.0 <https://aiolimiter.readthedocs.io/en/stable/>`_. Use this, if you want to use ``telegram.ext.AIORateLimiter``.
 * ``pip install python-telegram-bot[webhooks]`` installs the `tornado~=6.2 <https://www.tornadoweb.org/en/stable/>`_ library. Use this, if you want to use ``telegram.ext.Updater.start_webhook``/``telegram.ext.Application.start_webhook``.
 * ``pip install python-telegram-bot[callback-data]`` installs the `cachetools~=5.2.0 <https://cachetools.readthedocs.io/en/latest/>`_ library. Use this, if you want to use `arbitrary callback_data <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_.
 * ``pip install python-telegram-bot[job-queue]`` installs the `APScheduler~=3.9.1 <https://apscheduler.readthedocs.io/en/3.x/>`_ library and enforces `pytz>=2018.6 <https://pypi.org/project/pytz/>`_, where ``pytz`` is a dependency of ``APScheduler``. Use this, if you want to use the ``telegram.ext.JobQueue``.

README_RAW.rst

@@ -137,7 +137,7 @@ Optional Dependencies
 PTB can be installed with optional dependencies:
 
 * ``pip install python-telegram-bot-raw[passport]`` installs the `cryptography>=3.0 <https://cryptography.io/en/stable>`_ library. Use this, if you want to use Telegram Passport related functionality.
-* ``pip install python-telegram-bot-raw[socks]`` installs ``httpx[socks]``. Use this, if you want to work behind a Socks5 server.
+* ``pip install python-telegram-bot-raw[socks]`` installs `httpx[socks] <https://www.python-httpx.org/#dependencies>`_. Use this, if you want to work behind a Socks5 server.
 
 To install multiple optional dependencies, separate them by commas, e.g. ``pip install python-telegram-bot-raw[passport,socks]``.
 

docs/source/conf.py

@@ -44,11 +44,15 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
     "sphinx.ext.linkcode",
+    "sphinx.ext.extlinks",
     "sphinx_paramlinks",
     "sphinxcontrib.mermaid",
     "sphinx_search.extension",
 ]
 
+# For shorter links to Wiki in docstrings
+extlinks = {"wiki": ("https://github.com/python-telegram-bot/python-telegram-bot/wiki/%s", "%s")}
+
 # Use intersphinx to reference the python builtin library docs
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),

telegram/_bot.py

@@ -149,10 +149,8 @@ class Bot(TelegramObject, AbstractAsyncContextManager):
     .. seealso:: :attr:`telegram.ext.Application.bot`,
         :attr:`telegram.ext.CallbackContext.bot`,
         :attr:`telegram.ext.Updater.bot`,
-        `Your First Bot <https://github.com/\
-        python-telegram-bot/python-telegram-bot/wiki/Extensions-–-Your-first-Bot>`_,
-        `Builder Pattern <https://github.com/\
-        python-telegram-bot/python-telegram-bot/wiki/Builder-Pattern>`_
+        :wiki:`Your First Bot <Extensions-–-Your-first-Bot>`,
+        :wiki:`Builder Pattern <Builder-Pattern>`
 
     .. versionadded:: 13.2
         Objects of this class are comparable in terms of equality. Two objects of this class are
@@ -909,7 +907,8 @@ async def send_photo(
         """Use this method to send photos.
 
         .. seealso:: :meth:`telegram.Message.reply_photo`, :meth:`telegram.Chat.send_photo`,
-            :meth:`telegram.User.send_photo`
+            :meth:`telegram.User.send_photo`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@@ -1018,7 +1017,8 @@ async def send_audio(
         For sending voice messages, use the :meth:`send_voice` method instead.
 
         .. seealso:: :meth:`telegram.Message.reply_audio`, :meth:`telegram.Chat.send_audio`,
-            :meth:`telegram.User.send_audio`
+            :meth:`telegram.User.send_audio`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@@ -1139,7 +1139,8 @@ async def send_document(
         changed in the future.
 
         .. seealso:: :meth:`telegram.Message.reply_document`, :meth:`telegram.Chat.send_document`,
-            :meth:`telegram.User.send_document`
+            :meth:`telegram.User.send_document`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@@ -1248,7 +1249,8 @@ async def send_sticker(
         Use this method to send static ``.WEBP``, animated ``.TGS``, or video ``.WEBM`` stickers.
 
         .. seealso:: :meth:`telegram.Message.reply_sticker`, :meth:`telegram.Chat.send_sticker`,
-            :meth:`telegram.User.send_sticker`
+            :meth:`telegram.User.send_sticker`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@@ -1343,7 +1345,8 @@ async def send_video(
             changed by Telegram.
 
         .. seealso:: :meth:`telegram.Message.reply_video`, :meth:`telegram.Chat.send_video`,
-            :meth:`telegram.User.send_video`
+            :meth:`telegram.User.send_video`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@@ -1468,7 +1471,8 @@ async def send_video_note(
 
         .. seealso:: :meth:`telegram.Message.reply_video_note`,
             :meth:`telegram.Chat.send_video_note`,
-            :meth:`telegram.User.send_video_note`
+            :meth:`telegram.User.send_video_note`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@@ -1590,7 +1594,8 @@ async def send_animation(
 
         .. seealso:: :meth:`telegram.Message.reply_animation`,
             :meth:`telegram.Chat.send_animation`,
-            :meth:`telegram.User.send_animation`
+            :meth:`telegram.User.send_animation`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@@ -1715,7 +1720,8 @@ async def send_voice(
             sent as files.
 
         .. seealso:: :meth:`telegram.Message.reply_voice`, :meth:`telegram.Chat.send_voice`,
-            :meth:`telegram.User.send_voice`
+            :meth:`telegram.User.send_voice`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@@ -1824,7 +1830,8 @@ async def send_media_group(
 
         .. seealso:: :meth:`telegram.Message.reply_media_group`,
             :meth:`telegram.Chat.send_media_group`,
-            :meth:`telegram.User.send_media_group`
+            :meth:`telegram.User.send_media_group`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
@@ -2664,7 +2671,8 @@ async def answer_inline_query(
             :paramref:`telegram.InlineQuery.answer.auto_pagination` set to :obj:`True`, which will
             take care of passing the correct value.
 
-        .. seealso:: :meth:`telegram.InlineQuery.answer`
+        .. seealso:: :meth:`telegram.InlineQuery.answer`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             inline_query_id (:obj:`str`): Unique identifier for the answered query.
@@ -2812,7 +2820,8 @@ async def get_file(
             :meth:`telegram.Document.get_file`, :meth:`telegram.PassportFile.get_file`,
             :meth:`telegram.PhotoSize.get_file`, :meth:`telegram.Sticker.get_file`,
             :meth:`telegram.Video.get_file`, :meth:`telegram.VideoNote.get_file`,
-            :meth:`telegram.Voice.get_file`
+            :meth:`telegram.Voice.get_file`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             file_id (:obj:`str` | :class:`telegram.Animation` | :class:`telegram.Audio` |         \
@@ -3304,7 +3313,8 @@ async def edit_message_media(
             |editreplymarkup|
 
         .. seealso:: :meth:`telegram.Message.edit_media`,
-            :meth:`telegram.CallbackQuery.edit_message_media`
+            :meth:`telegram.CallbackQuery.edit_message_media`,
+            :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
 
         Args:
             media (:class:`telegram.InputMedia`): An object for a new media content
@@ -3556,9 +3566,9 @@ async def set_webhook(
                 integration.
             certificate (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | :obj:`str`):
                 Upload your public key certificate so that the root
-                certificate in use can be checked. See our `self-signed guide <https://github.com/\
-                python-telegram-bot/python-telegram-bot/wiki/Webhooks#creating-a-self-signed-\
-                certificate-using-openssl>`_ for details. |uploadinputnopath|
+                certificate in use can be checked. See our :wiki:`self-signed guide\
+                <Webhooks#creating-a-self-signed-certificate-using-openssl>` for details.
+                |uploadinputnopath|
             ip_address (:obj:`str`, optional): The fixed IP address which will be used to send
                 webhook requests instead of the IP address resolved through DNS.
             max_connections (:obj:`int`, optional): Maximum allowed number of simultaneous HTTPS

telegram/_chatmember.py

@@ -45,7 +45,7 @@ class ChatMember(TelegramObject):
     considered equal, if their :attr:`user` and :attr:`status` are equal.
 
     Examples:
-         :any:`Chat Member Bot <examples.chatmemberbot>`
+        :any:`Chat Member Bot <examples.chatmemberbot>`
 
     .. versionchanged:: 20.0
 

telegram/_dice.py

@@ -52,8 +52,8 @@ class Dice(TelegramObject):
 
         If :attr:`emoji` is :tg-const:`telegram.Dice.SLOT_MACHINE`, each value
         corresponds to a unique combination of symbols, which
-        can be found at our `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki\
-        /Code-snippets#map-a-slot-machine-dice-value-to-the-corresponding-symbols>`_.
+        can be found in our
+        :wiki:`wiki <Code-snippets#map-a-slot-machine-dice-value-to-the-corresponding-symbols>`.
         However, this behaviour is undocumented and might be changed by Telegram.
 
     ..

telegram/_files/file.py

@@ -141,6 +141,8 @@ async def download_to_drive(
             original file in order to decrypt the file without changing the existing one
             in-place.
 
+        .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
         .. versionchanged:: 20.0
 
             * :paramref:`custom_path` parameter now also accepts :class:`pathlib.Path` as argument.
@@ -224,6 +226,8 @@ async def download_to_memory(
         :obj:`io.BufferedIOBase`, the file contents will be saved to that object using the
         :obj:`out.write<io.BufferedIOBase.write>` method.
 
+        .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
         .. versionadded:: 20.0
 
         Args:

telegram/_files/inputmedia.py

@@ -44,6 +44,8 @@ class InputMedia(TelegramObject):
         Added arguments and attributes :attr:`type`, :attr:`media`, :attr:`caption`,
             :attr:`caption_entities`, :paramref:`parse_mode`.
 
+    .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
     Args:
         media_type (:obj:`str`): Type of media that the instance represents.
         media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
@@ -115,6 +117,8 @@ class InputMediaAnimation(InputMedia):
         width, height and duration from that video, unless otherwise specified with the optional
         arguments.
 
+    .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
     Args:
         media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
             :class:`telegram.Animation`): File to send. |fileinputnopath|
@@ -208,6 +212,8 @@ def __init__(
 class InputMediaPhoto(InputMedia):
     """Represents a photo to be sent.
 
+    .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
     Args:
         media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
             :class:`telegram.PhotoSize`): File to send. |fileinputnopath|
@@ -273,6 +279,8 @@ def __init__(
 class InputMediaVideo(InputMedia):
     """Represents a video to be sent.
 
+    .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
     Note:
         *  When using a :class:`telegram.Video` for the :attr:`media` attribute, it will take the
            width, height and duration from that video, unless otherwise specified with the optional
@@ -380,6 +388,8 @@ def __init__(
 class InputMediaAudio(InputMedia):
     """Represents an audio file to be treated as music to be sent.
 
+    .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
     Note:
         When using a :class:`telegram.Audio` for the :attr:`media` attribute, it will take the
         duration, performer and title from that video, unless otherwise specified with the
@@ -479,6 +489,8 @@ def __init__(
 class InputMediaDocument(InputMedia):
     """Represents a general file to be sent.
 
+    .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
     Args:
         media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
             :class:`telegram.Document`): File to send. |fileinputnopath|

telegram/_inline/inlinekeyboardbutton.py

@@ -95,8 +95,7 @@ class InlineKeyboardButton(TelegramObject):
             Tip:
                 The value entered here will be available in :attr:`telegram.CallbackQuery.data`.
 
-            .. seealso:: `Arbitrary callback_data <https://github.com/\
-                python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_
+            .. seealso:: :wiki:`Arbitrary callback_data <Arbitrary-callback_data>`
 
         web_app (:obj:`telegram.WebAppInfo`, optional): Description of the `Web App
             <https://core.telegram.org/bots/webapps>`_  that will be launched when the user presses

telegram/_inline/inlinequeryresultaudio.py

@@ -37,6 +37,8 @@ class InlineQueryResultAudio(InlineQueryResult):
     Alternatively, you can use :attr:`input_message_content` to send a message with the specified
     content instead of the audio.
 
+    .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
     Args:
         id (:obj:`str`): Unique identifier for this result,
             :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-

telegram/_inline/inlinequeryresultcachedaudio.py

@@ -37,6 +37,8 @@ class InlineQueryResultCachedAudio(InlineQueryResult):
     file will be sent by the user. Alternatively, you can use :attr:`input_message_content` to
     send a message with the specified content instead of the audio.
 
+    .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
     Args:
         id (:obj:`str`): Unique identifier for this result,
             :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-

telegram/_inline/inlinequeryresultcacheddocument.py

@@ -37,6 +37,8 @@ class InlineQueryResultCachedDocument(InlineQueryResult):
     by the user with an optional caption. Alternatively, you can use :attr:`input_message_content`
     to send a message with the specified content instead of the file.
 
+    .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
     Args:
         id (:obj:`str`): Unique identifier for this result,
             :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-

telegram/_inline/inlinequeryresultcachedgif.py

@@ -38,6 +38,8 @@ class InlineQueryResultCachedGif(InlineQueryResult):
     use :attr:`input_message_content` to send a message with specified content instead of
     the animation.
 
+    .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
     Args:
         id (:obj:`str`): Unique identifier for this result,
             :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-

telegram/_inline/inlinequeryresultcachedmpeg4gif.py

@@ -38,6 +38,8 @@ class InlineQueryResultCachedMpeg4Gif(InlineQueryResult):
     optional caption. Alternatively, you can use :attr:`input_message_content` to send a message
     with the specified content instead of the animation.
 
+    .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
     Args:
         id (:obj:`str`): Unique identifier for this result,
             :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-

telegram/_inline/inlinequeryresultcachedphoto.py

@@ -38,6 +38,8 @@ class InlineQueryResultCachedPhoto(InlineQueryResult):
     :attr:`input_message_content` to send a message with the specified content instead
     of the photo.
 
+    .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
     Args:
         id (:obj:`str`): Unique identifier for this result,
             :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-

telegram/_inline/inlinequeryresultcachedsticker.py

@@ -35,6 +35,8 @@ class InlineQueryResultCachedSticker(InlineQueryResult):
     be sent by the user. Alternatively, you can use :attr:`input_message_content` to send a
     message with the specified content instead of the sticker.
 
+    .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
     Args:
         id (:obj:`str`): Unique identifier for this result,
             :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-

telegram/_inline/inlinequeryresultcachedvideo.py

@@ -38,6 +38,8 @@ class InlineQueryResultCachedVideo(InlineQueryResult):
     :attr:`input_message_content` to send a message with the specified content instead
     of the video.
 
+    .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
     Args:
         id (:obj:`str`): Unique identifier for this result,
             :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-

telegram/_inline/inlinequeryresultcachedvoice.py

@@ -37,6 +37,8 @@ class InlineQueryResultCachedVoice(InlineQueryResult):
     message will be sent by the user. Alternatively, you can use :attr:`input_message_content` to
     send a message with the specified content instead of the voice message.
 
+    .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
     Args:
         id (:obj:`str`): Unique identifier for this result,
             :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-

telegram/_inline/inlinequeryresultdocument.py

@@ -38,6 +38,8 @@ class InlineQueryResultDocument(InlineQueryResult):
     specified content instead of the file. Currently, only .PDF and .ZIP files can be sent
     using this method.
 
+    .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
     Args:
         id (:obj:`str`): Unique identifier for this result,
             :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-

telegram/_inline/inlinequeryresultgif.py

@@ -37,6 +37,8 @@ class InlineQueryResultGif(InlineQueryResult):
     the user with optional caption. Alternatively, you can use :attr:`input_message_content` to
     send a message with the specified content instead of the animation.
 
+    .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
     Args:
         id (:obj:`str`): Unique identifier for this result,
             :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-

telegram/_inline/inlinequeryresultmpeg4gif.py

@@ -38,6 +38,8 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult):
     use :attr:`input_message_content` to send a message with the specified content instead of the
     animation.
 
+    .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
+
     Args:
         id (:obj:`str`): Unique identifier for this result,
             :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-