Documentation Improvements (#3628, #3636, #3694)

Co-authored-by: Yossi Rafelson <yossi.rafelson@gmail.com>
Co-authored-by: Aditya <clot27@apx_managed.vanilla>
Co-authored-by: ibragimovgeorge <103066850+ibragimovgeorge@users.noreply.github.com>

README.rst

@@ -46,8 +46,8 @@
    :target: https://app.codacy.com/gh/python-telegram-bot/python-telegram-bot/dashboard
    :alt: Code quality: Codacy
 
-.. image:: https://deepsource.io/gh/python-telegram-bot/python-telegram-bot.svg/?label=active+issues
-   :target: https://deepsource.io/gh/python-telegram-bot/python-telegram-bot/?ref=repository-badge
+.. image:: https://app.deepsource.com/gh/python-telegram-bot/python-telegram-bot.svg/?label=active+issues
+   :target: https://app.deepsource.com/gh/python-telegram-bot/python-telegram-bot/?ref=repository-badge
    :alt: Code quality: DeepSource
 
 .. image:: https://results.pre-commit.ci/badge/github/python-telegram-bot/python-telegram-bot/master.svg

README_RAW.rst

@@ -46,8 +46,8 @@
    :target: https://app.codacy.com/gh/python-telegram-bot/python-telegram-bot/dashboard
    :alt: Code quality: Codacy
 
-.. image:: https://deepsource.io/gh/python-telegram-bot/python-telegram-bot.svg/?label=active+issues
-   :target: https://deepsource.io/gh/python-telegram-bot/python-telegram-bot/?ref=repository-badge
+.. image:: https://app.deepsource.com/gh/python-telegram-bot/python-telegram-bot.svg/?label=active+issues
+   :target: https://app.deepsource.com/gh/python-telegram-bot/python-telegram-bot/?ref=repository-badge
    :alt: Code quality: DeepSource
 
 .. image:: https://results.pre-commit.ci/badge/github/python-telegram-bot/python-telegram-bot/master.svg

telegram/_bot.py

@@ -3616,7 +3616,7 @@ class Bot(TelegramObject, AsyncContextManager["Bot"]):
                 returned. An update is considered confirmed as soon as this method is called with
                 an offset higher than its :attr:`telegram.Update.update_id`. The negative offset
                 can be specified to retrieve updates starting from -offset update from the end of
-                the updates queue. All previous updates will forgotten.
+                the updates queue. All previous updates will be forgotten.
             limit (:obj:`int`, optional): Limits the number of updates to be retrieved. Values
                 between :tg-const:`telegram.constants.PollingLimit.MIN_LIMIT`-
                 :tg-const:`telegram.constants.PollingLimit.MAX_LIMIT` are accepted.

telegram/ext/_applicationbuilder.py

@@ -570,12 +570,13 @@ class ApplicationBuilder(Generic[BT, CCT, UD, CD, BD, JQ]):
 
         Note:
             Users have observed stability issues with HTTP/2, which happen due to how the `h2
-            library handles <https://github.com/python-hyper/h2/issues/1181>` cancellations of
+            library handles <https://github.com/python-hyper/h2/issues/1181>`_ cancellations of
             keepalive connections. See `#3556 <https://github.com/python-telegram-bot/
             python-telegram-bot/issues/3556>`_ for a discussion.
 
             If you want to use HTTP/2, you must install PTB with the optional requirement
             ``http2``, i.e.
+
             .. code-block:: bash
 
                pip install python-telegram-bot[http2]
@@ -728,7 +729,7 @@ class ApplicationBuilder(Generic[BT, CCT, UD, CD, BD, JQ]):
 
         Note:
             Users have observed stability issues with HTTP/2, which happen due to how the `h2
-            library handles <https://github.com/python-hyper/h2/issues/1181>` cancellations of
+            library handles <https://github.com/python-hyper/h2/issues/1181>`_ cancellations of
             keepalive connections. See `#3556 <https://github.com/python-telegram-bot/
             python-telegram-bot/issues/3556>`_ for a discussion.
 

telegram/ext/_jobqueue.py

@@ -291,6 +291,18 @@ class JobQueue(Generic[CCT]):
                   :attr:`telegram.ext.Defaults.tzinfo` is used.
 
                 Defaults to :paramref:`interval`
+
+                Note:
+                    Setting :paramref:`first` to ``0``, ``datetime.datetime.now()`` or another
+                    value that indicates that the job should run immediately will not work due
+                    to how the APScheduler library works. If you want to run a job immediately,
+                    we recommend to use an approach along the lines of::
+
+                        job = context.job_queue.run_repeating(callback, interval=5)
+                        await job.run(context.application)
+
+                    .. seealso:: :meth:`telegram.ext.Job.run`
+
             last (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta` |                        \
                    :obj:`datetime.datetime` | :obj:`datetime.time`, optional):
                 Latest possible time for the job to run. This parameter will be interpreted

telegram/ext/filters.py

@@ -141,7 +141,7 @@ class BaseFilter:
 
     Also works with more than two filters::
 
-        filters.TEXT & (filters.Entity(URL) | filters.Entity(TEXT_LINK))
+        filters.TEXT & (filters.Entity("url") | filters.Entity("text_link"))
         filters.TEXT & (~ filters.FORWARDED)
 
     Note:
@@ -514,7 +514,7 @@ class Caption(MessageFilter):
     allow those whose caption is appearing in the given list.
 
     Examples:
-        ``MessageHandler(filters.Caption(['PTB rocks!', 'PTB'], callback_method_2)``
+        ``MessageHandler(filters.Caption(['PTB rocks!', 'PTB']), callback_method_2)``
 
     .. seealso::
         :attr:`telegram.ext.filters.CAPTION`