Add Introductory Paragraphs to Telegram Types Subsections (#4389)

Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>

AUTHORS.rst

@@ -87,6 +87,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Miguel C. R. <https://github.com/MiguelX413>`_
 - `miles <https://github.com/miles170>`_
 - `Mischa Krüger <https://github.com/Makman2>`_
+- `Mohd Yusuf <https://github.com/mohdyusuf2312>`_
 - `naveenvhegde <https://github.com/naveenvhegde>`_
 - `neurrone <https://github.com/neurrone>`_
 - `NikitaPirate <https://github.com/NikitaPirate>`_

docs/source/telegram.games-tree.rst

@@ -1,6 +1,21 @@
+.. _games-tree:
+
 Games
 -----
 
+Your bot can offer users **HTML5 games** to play solo or to compete against each other in groups and one-on-one chats. Create games via `@BotFather <https://telegram.me/BotFather>`_ using the ``/newgame`` command. Please note that this kind of power requires responsibility: you will need to accept the terms for each game that your bots will be offering.
+
+* Games are a new type of content on Telegram, represented by the :class:`telegram.Game` and :class:`telegram.InlineQueryResultGame` objects.
+* Once you've created a game via `BotFather <https://t.me/botfather>`_, you can send games to chats as regular messages using the :meth:`~telegram.Bot.sendGame` method, or use :ref:`inline mode <inline-tree>` with :class:`telegram.InlineQueryResultGame`.
+* If you send the game message without any buttons, it will automatically have a 'Play ``GameName``' button. When this button is pressed, your bot gets a :class:`telegram.CallbackQuery` with the ``game_short_name`` of the requested game. You provide the correct URL for this particular user and the app opens the game in the in-app browser.
+* You can manually add multiple buttons to your game message. Please note that the first button in the first row **must always** launch the game, using the field ``callback_game`` in :class:`telegram.InlineKeyboardButton`. You can add extra buttons according to taste: e.g., for a description of the rules, or to open the game's official community.
+* To make your game more attractive, you can upload a GIF animation that demonstrates the game to the users via `BotFather <https://t.me/botfather>`_ (see `Lumberjack <https://t.me/gamebot?game=lumberjack>`_ for example).
+* A game message will also display high scores for the current chat. Use :meth:`~telegram.Bot.setGameScore` to post high scores to the chat with the game, optionally add the :paramref:`~telegram.Bot.set_game_score.disable_edit_message` parameter if you don't want to automatically update the message with the current scoreboard.
+* Use :meth:`~telegram.Bot.getGameHighScores` to get data for in-game high score tables.
+* You can also add an extra sharing button for users to share their best score to different chats.
+* For examples of what can be done using this new stuff, check the `@gamebot <https://t.me/gamebot>`_ and `@gamee <https://t.me/gamee>`_ bots.
+
+
 .. toctree::
     :titlesonly:
 

docs/source/telegram.inline-tree.rst

@@ -1,6 +1,14 @@
+.. _inline-tree:
+
 Inline Mode
 -----------
 
+The following methods and objects allow your bot to work in `inline mode <https://core.telegram.org/bots/inline>`_. 
+Please see Telegrams `Introduction to Inline bots <https://core.telegram.org/bots/inline>`_ for more details.
+
+To enable this option, send the ``/setinline`` command to `@BotFather <https://t.me/botfather>`_ and provide the placeholder text that the user will see in the input field after typing your bot's name.
+
+
 .. toctree::
     :titlesonly:
 

docs/source/telegram.passport-tree.rst

@@ -1,6 +1,9 @@
 Passport
 --------
 
+Passport is a unified authorization method for services that require personal identification. Users can upload their documents once, then instantly share their data with services that require real-world ID (finance, ICOs, etc.). Please see the `manual <https://core.telegram.org/passport>`_ for details.
+
+
 .. toctree::
     :titlesonly:
 

docs/source/telegram.payments-tree.rst

@@ -1,6 +1,11 @@
+.. _payments-tree:
+
 Payments
 --------
 
+Your bot can accept payments from Telegram users. Please see the `introduction to payments <https://core.telegram.org/bots/payments>`_ for more details on the process and how to set up payments for your bot.
+
+
 .. toctree::
     :titlesonly:
 

docs/source/telegram.stickers-tree.rst

@@ -1,6 +1,8 @@
 Stickers
 --------
 
+The following methods and objects allow your bot to handle stickers and sticker sets.
+
 .. toctree::
     :titlesonly:
 

telegram/_message.py

@@ -359,7 +359,7 @@ class Message(MaybeInaccessibleMessage):
             about the animation. For backward compatibility, when this field is set, the document
             field will also be set.
         game (:class:`telegram.Game`, optional): Message is a game, information about the game.
-            `More about games >> <https://core.telegram.org/bots/api#games>`_.
+            :ref:`More about games >> <games-tree>`.
         photo (Sequence[:class:`telegram.PhotoSize`], optional): Message is a photo, available
             sizes of the photo. This list is empty if the message does not contain a photo.
 
@@ -432,10 +432,10 @@ class Message(MaybeInaccessibleMessage):
                 :class:`telegram.InaccessibleMessage`.
         invoice (:class:`telegram.Invoice`, optional): Message is an invoice for a payment,
             information about the invoice.
-            `More about payments >> <https://core.telegram.org/bots/api#payments>`_.
+            :ref:`More about payments >> <payments-tree>`.
         successful_payment (:class:`telegram.SuccessfulPayment`, optional): Message is a service
             message about a successful payment, information about the payment.
-            `More about payments >> <https://core.telegram.org/bots/api#payments>`_.
+            :ref:`More about payments >> <payments-tree>`.
         connected_website (:obj:`str`, optional): The domain name of the website on which the user
             has logged in.
             `More about Telegram Login >> <https://core.telegram.org/widgets/login>`_.
@@ -676,7 +676,7 @@ class Message(MaybeInaccessibleMessage):
 
             .. seealso:: :wiki:`Working with Files and Media <Working-with-Files-and-Media>`
         game (:class:`telegram.Game`): Optional. Message is a game, information about the game.
-            `More about games >> <https://core.telegram.org/bots/api#games>`_.
+            :ref:`More about games >> <games-tree>`.
         photo (Tuple[:class:`telegram.PhotoSize`]): Optional. Message is a photo, available
             sizes of the photo. This list is empty if the message does not contain a photo.
 
@@ -758,10 +758,10 @@ class Message(MaybeInaccessibleMessage):
                 :class:`telegram.InaccessibleMessage`.
         invoice (:class:`telegram.Invoice`): Optional. Message is an invoice for a payment,
             information about the invoice.
-            `More about payments >> <https://core.telegram.org/bots/api#payments>`_.
+            :ref:`More about payments >> <payments-tree>`.
         successful_payment (:class:`telegram.SuccessfulPayment`): Optional. Message is a service
             message about a successful payment, information about the payment.
-            `More about payments >> <https://core.telegram.org/bots/api#payments>`_.
+            :ref:`More about payments >> <payments-tree>`.
         connected_website (:obj:`str`): Optional. The domain name of the website on which the user
             has logged in.
             `More about Telegram Login >> <https://core.telegram.org/widgets/login>`_.

telegram/_reply.py

@@ -92,14 +92,13 @@ class ExternalReplyInfo(TelegramObject):
             about the contact.
         dice (:class:`telegram.Dice`, optional): Message is a dice with random value.
         game (:Class:`telegram.Game`. optional): Message is a game, information about the game.
-            `More about games >> <https://core.telegram.org/bots/api#games>`_.
+            :ref:`More about games >> <games-tree>`.
         giveaway (:class:`telegram.Giveaway`, optional): Message is a scheduled giveaway,
             information about the giveaway.
         giveaway_winners (:class:`telegram.GiveawayWinners`, optional): A giveaway with public
             winners was completed.
         invoice (:class:`telegram.Invoice`, optional): Message is an invoice for a payment,
-            information about the invoice. `More about payments >>
+            information about the invoice. :ref:`More about payments >> <payments-tree>`.
-            <https://core.telegram.org/bots/api#payments>`_.
         location (:class:`telegram.Location`, optional): Message is a shared location, information
             about the location.
         poll (:class:`telegram.Poll`, optional): Message is a native poll, information about the
@@ -142,14 +141,13 @@ class ExternalReplyInfo(TelegramObject):
             about the contact.
         dice (:class:`telegram.Dice`): Optional. Message is a dice with random value.
         game (:Class:`telegram.Game`): Optional. Message is a game, information about the game.
-            `More about games >> <https://core.telegram.org/bots/api#games>`_.
+            :ref:`More about games >> <games-tree>`.
         giveaway (:class:`telegram.Giveaway`): Optional. Message is a scheduled giveaway,
             information about the giveaway.
         giveaway_winners (:class:`telegram.GiveawayWinners`): Optional. A giveaway with public
             winners was completed.
         invoice (:class:`telegram.Invoice`): Optional. Message is an invoice for a payment,
-            information about the invoice. `More about payments >>
+            information about the invoice. :ref:`More about payments >> <payments-tree>`.
-            <https://core.telegram.org/bots/api#payments>`_.
         location (:class:`telegram.Location`): Optional. Message is a shared location, information
             about the location.
         poll (:class:`telegram.Poll`): Optional. Message is a native poll, information about the