Documentation Improvements (#3698, #3708, #3767)

Co-authored-by: Iulian Onofrei <5748627+revolter@users.noreply.github.com>
Co-authored-by: Poolitzer <github@poolitzer.eu>
Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>
Co-authored-by: Aditya <clot27@apx_managed.vanilla>

.github/CONTRIBUTING.rst

@@ -274,25 +274,6 @@ callable we prefer that the call also uses keyword arg syntax. For example:
 This gives us the flexibility to re-order arguments and more importantly
 to add new required arguments. It's also more explicit and easier to read.
 
-Properly defining optional arguments
-------------------------------------
-
-It's always good to not initialize optional arguments at class creation,
-instead use ``**kwargs`` to get them. It's well known Telegram API can
-change without notice, in that case if a new argument is added it won't
-break the API classes. For example:
-
-.. code-block:: python
-
-    # GOOD
-    def __init__(self, id, name, last_name=None, **kwargs):
-        self.last_name = last_name
-
-
-    # BAD
-    def __init__(self, id, name, last_name=None):
-        self.last_name = last_name
-
 
 .. _`Code of Conduct`: https://www.python.org/psf/conduct/
 .. _`issue tracker`: https://github.com/python-telegram-bot/python-telegram-bot/issues

AUTHORS.rst

@@ -57,6 +57,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Harshil <https://github.com/harshil21>`_
 - `Hugo Damer <https://github.com/HakimusGIT>`_
 - `ihoru <https://github.com/ihoru>`_
+- `Iulian Onofrei <https://github.com/revolter>`_
 - `Jasmin Bom <https://github.com/jsmnbom>`_
 - `JASON0916 <https://github.com/JASON0916>`_
 - `jeffffc <https://github.com/jeffffc>`_

README.rst

@@ -167,7 +167,7 @@ Quick Start
 ===========
 
 Our Wiki contains an `Introduction to the API <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Introduction-to-the-API>`_ explaining how the pure Bot API can be accessed via ``python-telegram-bot``.
-Moreover, the `Tutorial: Your first Bot <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions-%E2%80%93-Your-first-Bot>`_ gives an introduction on how chatbots can be easily programmed with the help of the ``telegram.ext`` module.
+Moreover, the `Tutorial: Your first Bot <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions---Your-first-Bot>`_ gives an introduction on how chatbots can be easily programmed with the help of the ``telegram.ext`` module.
 
 Resources
 =========
@@ -209,7 +209,7 @@ 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 or feature requests <https://github.com/python-telegram-bot/python-telegram-bot/issues/new>`_.
+You can also help by `reporting bugs or feature requests <https://github.com/python-telegram-bot/python-telegram-bot/issues/new/choose>`_.
 
 Donating
 ========

README_RAW.rst

@@ -195,7 +195,7 @@ 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 or feature requests <https://github.com/python-telegram-bot/python-telegram-bot/issues/new>`_.
+You can also help by `reporting bugs or feature requests <https://github.com/python-telegram-bot/python-telegram-bot/issues/new/choose>`_.
 
 Donating
 ========

docs/source/conf.py

@@ -44,7 +44,11 @@ extensions = [
 ]
 
 # For shorter links to Wiki in docstrings
-extlinks = {"wiki": ("https://github.com/python-telegram-bot/python-telegram-bot/wiki/%s", "%s")}
+extlinks = {
+    "wiki": ("https://github.com/python-telegram-bot/python-telegram-bot/wiki/%s", "%s"),
+    "pr": ("https://github.com/python-telegram-bot/python-telegram-bot/pull/%s", "#%s"),
+    "issue": ("https://github.com/python-telegram-bot/python-telegram-bot/issues/%s", "#%s"),
+}
 
 # Use intersphinx to reference the python builtin library docs
 intersphinx_mapping = {

docs/source/examples.rst

@@ -38,8 +38,7 @@ class to send timed messages. The user sets a timer by using ``/set``
 command with a specific time, for example ``/set 30``. The bot then sets
 up a job to send a message to that user after 30 seconds. The user can
 also cancel the timer by sending ``/unset``. To learn more about the
-``JobQueue``, read `this wiki
+``JobQueue``, read `this wiki article <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions---JobQueue>`__.
-article <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions-%E2%80%93-JobQueue>`__.
 Note: To use ``JobQueue``, you must install PTB via ``pip install "python-telegram-bot[job-queue]"``
 
 :any:`examples.conversationbot`

docs/source/stability_policy.rst

@@ -29,7 +29,7 @@ Objects are in general not guaranteed to be pickleable (unless stated otherwise)
 We may provide a way to convert pickled objects from one version to another, but this is not guaranteed.
 
 Functionality that is part of PTBs API but is explicitly documented as not being intended to be used directly by users (e.g. :meth:`telegram.request.BaseRequest.do_request`) may change.
-This also applies to functions or attributes marked as final in the sense of `PEP 591 <https://www.python.org/dev/peps/pep-0591/>`__.
+This also applies to functions or attributes marked as final in the sense of `PEP 591 <https://peps.python.org/pep-0591/>`__.
 
 PTB has dependencies to third-party packages.
 The versions that PTB uses of these third-party packages may change if that does not affect PTBs public API.

examples/inlinebot.py

@@ -98,7 +98,7 @@ def main() -> None:
     application.add_handler(CommandHandler("start", start))
     application.add_handler(CommandHandler("help", help_command))
 
-    # on non command i.e message - echo the message on Telegram
+    # on inline queries - show corresponding inline results
     application.add_handler(InlineQueryHandler(inline_query))
 
     # Run the bot until the user presses Ctrl-C

telegram/_bot.py

@@ -4952,6 +4952,14 @@ class Bot(TelegramObject, AsyncContextManager["Bot"]):
         administrator in the chat for this to work and must have the appropriate admin rights.
         The link can be revoked using the method :meth:`revoke_chat_invite_link`.
 
+        Note:
+            When joining *public* groups via an invite link, Telegram clients may display the
+            usual "Join" button, effectively ignoring the invite link. In particular, the parameter
+            :paramref:`creates_join_request` has no effect in this case.
+            However, this behavior is undocument and may be subject to change.
+            See `this GitHub thread <https://github.com/tdlib/telegram-bot-api/issues/429>`_
+            for some discussion.
+
         .. versionadded:: 13.4
 
         Args:

telegram/_chatjoinrequest.py

@@ -92,6 +92,12 @@ class ChatJoinRequest(TelegramObject):
         invite_link (:class:`telegram.ChatInviteLink`): Optional. Chat invite link that was used
             by the user to send the join request.
 
+            Note:
+                When a user joins a *public* group via an invite link, this attribute may not
+                be present. However, this behavior is undocument and may be subject to change.
+                See `this GitHub thread <https://github.com/tdlib/telegram-bot-api/issues/428>`_
+                for some discussion.
+
     """
 
     __slots__ = ("chat", "from_user", "date", "bio", "invite_link", "user_chat_id")

telegram/ext/_application.py

@@ -379,7 +379,7 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AsyncContextManager["Applica
         :class:`telegram.ext.JobQueue`: The :class:`JobQueue` used by the
             :class:`telegram.ext.Application`.
 
-        .. seealso:: :wiki:`Job Queue <Extensions-%E2%80%93-JobQueue>`
+        .. seealso:: :wiki:`Job Queue <Extensions---JobQueue>`
         """
         if self._job_queue is None:
             warn(

telegram/ext/_applicationbuilder.py

@@ -965,7 +965,7 @@ class ApplicationBuilder(Generic[BT, CCT, UD, CD, BD, JQ]):
         Examples:
             :any:`Timer Bot <examples.timerbot>`
 
-        .. seealso:: :wiki:`Job Queue <Extensions-%E2%80%93-JobQueue>`
+        .. seealso:: :wiki:`Job Queue <Extensions---JobQueue>`
 
         Note:
             * :meth:`telegram.ext.JobQueue.set_application` will be called automatically by

telegram/ext/_callbackcontext.py

@@ -84,7 +84,7 @@ class CallbackContext(Generic[BT, UD, CD, BD]):
         * :any:`Custom Webhook Bot <examples.customwebhookbot>`
 
     .. seealso:: :attr:`telegram.ext.ContextTypes.DEFAULT_TYPE`,
-        :wiki:`Job Queue <Extensions-%E2%80%93-JobQueue>`
+        :wiki:`Job Queue <Extensions---JobQueue>`
 
     Args:
         application (:class:`telegram.ext.Application`): The application associated with this
@@ -399,7 +399,7 @@ class CallbackContext(Generic[BT, UD, CD, BD]):
         :class:`telegram.ext.JobQueue`: The :class:`JobQueue` used by the
         :class:`telegram.ext.Application`.
 
-        .. seealso:: :wiki:`Job Queue <Extensions-%E2%80%93-JobQueue>`
+        .. seealso:: :wiki:`Job Queue <Extensions---JobQueue>`
         """
         if self._application._job_queue is None:  # pylint: disable=protected-access
             warn(

telegram/ext/_jobqueue.py

@@ -66,7 +66,7 @@ class JobQueue(Generic[CCT]):
         :any:`Timer Bot <examples.timerbot>`
 
     .. seealso:: :wiki:`Architecture Overview <Architecture>`,
-        :wiki:`Job Queue <Extensions-%E2%80%93-JobQueue>`
+        :wiki:`Job Queue <Extensions---JobQueue>`
 
     .. versionchanged:: 20.0
         To use this class, PTB must be installed via
@@ -690,7 +690,7 @@ class Job(Generic[CCT]):
         This class should not be instantiated manually.
         Use the methods of :class:`telegram.ext.JobQueue` to schedule jobs.
 
-    .. seealso:: :wiki:`Job Queue <Extensions-%E2%80%93-JobQueue>`
+    .. seealso:: :wiki:`Job Queue <Extensions---JobQueue>`
 
     .. versionchanged:: 20.0
 

telegram/request/_requestdata.py

@@ -33,8 +33,8 @@ class RequestData:
     .. versionadded:: 20.0
 
     Warning:
-        How exactly instances of this will are created should be considered an implementation
+        How exactly instances of this are created should be considered an implementation detail
-        detail and not part of PTBs public API. Users should exclusively rely on the documented
+        and not part of PTBs public API. Users should exclusively rely on the documented
         attributes, properties and methods.
 
     Attributes: