Documentation Improvements (#5240)

Co-authored-by: Poolitzer <github@poolitzer.eu>

changes/unreleased/5240.iJXyH8RNWNNQpC47SfNHzw.toml

@@ -0,0 +1,6 @@
+documentation = "Documentation Improvements"
+
+pull_requests = [
+    { uid = "5240", author_uids = ["harshil21", "Poolitzer"] },
+    { uid = "5241", author_uids = ["harshil21"] },
+]

docs/auxil/bot_insertion.py

@@ -83,6 +83,13 @@ get_updates_read_timeout_addition = [
     "           ``2``.",
 ]
 
+RAISES_BLOCK = [
+    "Raises:",
+    "",
+    "    :class:`telegram.error.TelegramError`",
+    "",
+]
+
 
 def find_insert_pos_for_kwargs(lines: list[str]) -> int:
     """Finds the correct position to insert the keyword arguments and returns the index."""
@@ -92,6 +99,13 @@ def find_insert_pos_for_kwargs(lines: list[str]) -> int:
     return False
 
 
+def find_insert_pos_for_raises(lines: list[str]) -> int:
+    """Finds the correct position to insert the Raises block and returns the index."""
+    if "Raises:" in lines:
+        return -1  # Don't insert if there's already a Raises block
+    return len(lines)  # Insert at the end if there's no Raises block
+
+
 def check_timeout_and_api_kwargs_presence(obj: object) -> int:
     """Checks if the method has timeout and api_kwargs keyword only parameters."""
     sig = inspect.signature(obj)

docs/auxil/sphinx_hooks.py

@@ -27,9 +27,11 @@ from sphinx.application import Sphinx
 import telegram
 import telegram.ext
 from docs.auxil.admonition_inserter import AdmonitionInserter
-from docs.auxil.kwargs_insertion import (
+from docs.auxil.bot_insertion import (
+    RAISES_BLOCK,
     check_timeout_and_api_kwargs_presence,
     find_insert_pos_for_kwargs,
+    find_insert_pos_for_raises,
     get_updates_read_timeout_addition,
     keyword_args,
     media_write_timeout_change,
@@ -85,8 +87,8 @@ def autodoc_process_docstring(
     app: Sphinx, what, name: str, obj: object, options, lines: list[str]
 ):
     """We do the following things:
-    1) Use this method to automatically insert the Keyword Args and "Shortcuts" admonitions
+    1) Use this method to automatically insert the Keyword Args, "Shortcuts" admonitions,
-       for the Bot methods.
+       and the Raises block, wherever applicable, for the Bot methods.
 
     2) Use this method to automatically insert "Returned in" admonition into classes
        that are returned from the Bot methods
@@ -102,13 +104,15 @@ def autodoc_process_docstring(
     """
 
     # 1) Insert the Keyword Args and "Shortcuts" admonitions for the Bot methods
-    method_name = name.rsplit(".", maxsplit=1)[0]
+    method_name = name.rsplit(".", maxsplit=1)[-1]
     if (
         name.startswith("telegram.Bot.")
         and what == "method"
         and method_name.islower()
         and check_timeout_and_api_kwargs_presence(obj)
     ):
+        # Logic for inserting keyword args into docstrings:
+        # -------------------------------------------------
         insert_index = find_insert_pos_for_kwargs(lines)
         if not insert_index:
             raise ValueError(
@@ -134,6 +138,16 @@ def autodoc_process_docstring(
             lines[insert_idx:insert_idx] = effective_insert
             insert_idx += len(effective_insert)
 
+        # Logic for inserting Raises:
+        # -------------------------------------------------
+        # We will only insert the Raises block if there isn't already one.
+
+        insert_index = find_insert_pos_for_raises(lines)
+        if insert_index != -1:
+            lines[insert_index:insert_index] = RAISES_BLOCK
+
+        # Logic for inserting "Shortcuts" admonition:
+        # -------------------------------------------
         ADMONITION_INSERTER.insert_admonitions(
             obj=typing.cast("collections.abc.Callable", obj),
             docstring_lines=lines,

docs/source/telegram.at-tree.rst

@@ -165,6 +165,7 @@ Available Types
     telegram.poll
     telegram.pollanswer
     telegram.pollmedia
+    telegram.polloption
     telegram.polloptionadded
     telegram.polloptiondeleted
     telegram.preparedkeyboardbutton

src/telegram/__init__.py

@@ -419,11 +419,6 @@ from ._copytextbutton import CopyTextButton
 from ._dice import Dice
 from ._directmessagepricechanged import DirectMessagePriceChanged
 from ._directmessagestopic import DirectMessagesTopic
-from ._files._inputstorycontent import (
-    InputStoryContent,
-    InputStoryContentPhoto,
-    InputStoryContentVideo,
-)
 from ._files.animation import Animation
 from ._files.audio import Audio
 from ._files.chatphoto import ChatPhoto
@@ -455,6 +450,11 @@ from ._files.inputprofilephoto import (
     InputProfilePhotoStatic,
 )
 from ._files.inputsticker import InputSticker
+from ._files.inputstorycontent import (
+    InputStoryContent,
+    InputStoryContentPhoto,
+    InputStoryContentVideo,
+)
 from ._files.livephoto import LivePhoto
 from ._files.location import Location
 from ._files.photosize import PhotoSize

src/telegram/_files/video.py

@@ -105,7 +105,7 @@ class Video(_BaseThumbedMedium):
 
             .. deprecated:: v22.2
                 |time-period-int-deprecated|
-        qualities (Sequence[:class:`telegram.VideoQuality`]): Optional. List of available qualities
+        qualities (tuple[:class:`telegram.VideoQuality`]): Optional. List of available qualities
             of the video
 
             .. versionadded:: 22.7

src/telegram/_message.py

@@ -693,7 +693,7 @@ class Message(MaybeInaccessibleMessage):
 
             .. versionadded:: 22.7
         sender_tag (:obj:`str`, optional): Tag or custom title of the sender of the message; for
-            supergroups only
+            supergroups only.
 
             .. versionadded:: 22.7
         poll_option_added (:class:`telegram.PollOptionAdded`, optional): Service message:
@@ -1146,7 +1146,7 @@ class Message(MaybeInaccessibleMessage):
 
             .. versionadded:: 22.7
         sender_tag (:obj:`str`): Optional. Tag or custom title of the sender of the message; for
-            supergroups only
+            supergroups only.
 
             .. versionadded:: 22.7
         poll_option_added (:class:`telegram.PollOptionAdded`): Optional. Service message:

src/telegram/request/_requestparameter.py

@@ -24,11 +24,11 @@ from collections.abc import Sequence
 from dataclasses import dataclass
 from typing import final
 
-from telegram._files._inputstorycontent import InputStoryContent
 from telegram._files.inputfile import InputFile
 from telegram._files.inputmedia import InputMedia, InputPaidMedia
 from telegram._files.inputprofilephoto import InputProfilePhoto, InputProfilePhotoStatic
 from telegram._files.inputsticker import InputSticker
+from telegram._files.inputstorycontent import InputStoryContent
 from telegram._telegramobject import TelegramObject
 from telegram._utils.datetime import to_timestamp
 from telegram._utils.enum import StringEnum

tests/test_business_methods.py

@@ -33,7 +33,7 @@ from telegram import (
     StoryAreaTypeUniqueGift,
     User,
 )
-from telegram._files._inputstorycontent import InputStoryContentVideo
+from telegram._files.inputstorycontent import InputStoryContentVideo
 from telegram._files.sticker import Sticker
 from telegram._gifts import AcceptedGiftTypes, Gift
 from telegram._inline.inlinekeyboardbutton import InlineKeyboardButton