Doc Fixes (#2225)

* Fix dscr for soccer ball values

* Update docs of BasePersistence regarding abc

* elaborate run_daily docs

* Make docstring of send_document.filename more precise

* increase bot API and add Discussion link

Co-authored-by: Poolitzer <25934244+Poolitzer@users.noreply.github.com>

README.rst

@@ -96,7 +96,7 @@ make the development of bots easy and straightforward. These classes are contain
 Telegram API support
 ====================
 
-All types and methods of the Telegram Bot API **4.8** are supported.
+All types and methods of the Telegram Bot API **5.0** are supported.
 
 ==========
 Installing
@@ -192,7 +192,7 @@ You can get help in several ways:
 
 2. In case you are unable to join our group due to Telegram restrictions, you can use our `IRC channel <https://webchat.freenode.net/?channels=##python-telegram-bot>`_.
 
-3. Report bugs, request new features or ask questions by `creating an issue <https://github.com/python-telegram-bot/python-telegram-bot/issues/new/choose>`_.
+3. Report bugs, request new features or ask questions by `creating an issue <https://github.com/python-telegram-bot/python-telegram-bot/issues/new/choose>`_ or `a discussion <https://github.com/python-telegram-bot/python-telegram-bot/discussions/new>`_.
 
 4. Our `Wiki pages <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ offer a growing amount of resources.
 

telegram/dice.py

@@ -41,7 +41,7 @@ class Dice(TelegramObject):
         3 indicates that the basket was missed. However, this behaviour is undocumented and might
         be changed by Telegram.
 
-        If :attr:`emoji` is "⚽", a value of 3 to 5 currently scores a goal, while a value of 1 to
+        If :attr:`emoji` is "⚽", a value of 4 to 5 currently scores a goal, while a value of 1 to
         3 indicates that the goal was missed. However, this behaviour is undocumented and might
         be changed by Telegram.
 

telegram/ext/basepersistence.py

@@ -31,17 +31,20 @@ class BasePersistence(ABC):
     """Interface class for adding persistence to your bot.
     Subclass this object for different implementations of a persistent bot.
 
-    All relevant methods must be overwritten. This means:
+    All relevant methods must be overwritten. This includes:
 
-    * If :attr:`store_bot_data` is :obj:`True` you must overwrite :meth:`get_bot_data` and
-      :meth:`update_bot_data`.
-    * If :attr:`store_chat_data` is :obj:`True` you must overwrite :meth:`get_chat_data` and
-      :meth:`update_chat_data`.
-    * If :attr:`store_user_data` is :obj:`True` you must overwrite :meth:`get_user_data` and
-      :meth:`update_user_data`.
-    * If you want to store conversation data with :class:`telegram.ext.ConversationHandler`, you
-      must overwrite :meth:`get_conversations` and :meth:`update_conversation`.
-    * :meth:`flush` will be called when the bot is shutdown.
+    * meth:`get_bot_data`
+    * :meth:`update_bot_data`
+    * :meth:`get_chat_data`
+    * :meth:`update_chat_data`
+    * :meth:`get_user_data`
+    * :meth:`update_user_data`
+    * :meth:`get_conversations`
+    * :meth:`update_conversation`
+    * :meth:`flush`
+
+    If you don't actually need one of those methods, a simple ``pass`` is enough. For example, if
+    ``store_bot_data=False``, you don't need :meth:`get_bot_data` and :meth:`update_bot_data.
 
     Warning:
         Persistence will try to replace :class:`telegram.Bot` instances by :attr:`REPLACED_BOT` and
@@ -287,7 +290,7 @@ class BasePersistence(ABC):
     @abstractmethod
     def get_user_data(self) -> DefaultDict[int, Dict[Any, Any]]:
         """ "Will be called by :class:`telegram.ext.Dispatcher` upon creation with a
-        persistence object. It should return the user_data if stored, or an empty
+        persistence object. It should return the ``user_data`` if stored, or an empty
         ``defaultdict(dict)``.
 
         Returns:
@@ -297,7 +300,7 @@ class BasePersistence(ABC):
     @abstractmethod
     def get_chat_data(self) -> DefaultDict[int, Dict[Any, Any]]:
         """ "Will be called by :class:`telegram.ext.Dispatcher` upon creation with a
-        persistence object. It should return the chat_data if stored, or an empty
+        persistence object. It should return the ``chat_data`` if stored, or an empty
         ``defaultdict(dict)``.
 
         Returns:
@@ -307,7 +310,7 @@ class BasePersistence(ABC):
     @abstractmethod
     def get_bot_data(self) -> Dict[Any, Any]:
         """ "Will be called by :class:`telegram.ext.Dispatcher` upon creation with a
-        persistence object. It should return the bot_data if stored, or an empty
+        persistence object. It should return the ``bot_data`` if stored, or an empty
         :obj:`dict`.
 
         Returns:
@@ -372,8 +375,7 @@ class BasePersistence(ABC):
 
     def flush(self) -> None:
         """Will be called by :class:`telegram.ext.Updater` upon receiving a stop signal. Gives the
-        persistence a chance to finish up saving or close a database connection gracefully. If this
-        is not of any importance just pass will be sufficient.
+        persistence a chance to finish up saving or close a database connection gracefully.
         """
 
     REPLACED_BOT: ClassVar[str] = 'bot_instance_replaced_by_ptb_persistence'

telegram/ext/dispatcher.py

@@ -636,7 +636,7 @@ class Dispatcher:
         """Dispatches an error.
 
         Args:
-            update (:obj:`Any` | :class:`telegram.Update` | None): The update that caused the error.
+            update (:obj:`Any` | :class:`telegram.Update`): The update that caused the error.
             error (:obj:`Exception`): The error that was raised.
             promise (:class:`telegram.utils.Promise`, optional): The promise whose pooled function
                 raised the error.

telegram/ext/jobqueue.py

@@ -409,7 +409,7 @@ class JobQueue:
             time (:obj:`datetime.time`): Time of day at which the job should run. If the timezone
                 (``time.tzinfo``) is :obj:`None`, the default timezone of the bot will be used.
             days (Tuple[:obj:`int`], optional): Defines on which days of the week the job should
-                run. Defaults to ``EVERY_DAY``
+                run (where ``0-6`` correspond to monday - sunday). Defaults to ``EVERY_DAY``
             context (:obj:`object`, optional): Additional data needed for the callback function.
                 Can be accessed through ``job.context`` in the callback. Defaults to :obj:`None`.
             name (:obj:`str`, optional): The name of the new job. Defaults to