Sphinx restructuring: Now builds PDF and better HTML docs (#449)

* update sphinx source files to properly build latexpdf and improve html build

* fix docstrings and sphinx sources to get rid of warnings

* add telegram.contrib.rst

docs/source/conf.py

@@ -209,6 +209,9 @@ htmlhelp_basename = 'PythonTelegramBotdoc'
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
+    'preamble': '''\\setcounter{tocdepth}{2}
+\\usepackage{enumitem}
+\\setlistdepth{99}''',
 # The paper size ('letterpaper' or 'a4paper').
 #'papersize': 'letterpaper',
 

docs/source/index.rst

@@ -10,7 +10,7 @@ Contents:
    telegram
 
 .. toctree::
-   :maxdepth: 2
+   telegram
 
 
 

docs/source/modules.rst

@@ -1,7 +0,0 @@
-telegram
-========
-
-.. toctree::
-   :maxdepth: 4
-
-   telegram

docs/source/telegram.contrib.rst

@@ -0,0 +1,17 @@
+telegram.contrib package
+========================
+
+Submodules
+----------
+
+.. toctree::
+
+    telegram.contrib.botan
+
+Module contents
+---------------
+
+.. automodule:: telegram.contrib
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/telegram.ext.rst

@@ -10,6 +10,7 @@ Submodules
     telegram.ext.dispatcher
     telegram.ext.jobqueue
     telegram.ext.handler
+    telegram.ext.callbackqueryhandler
     telegram.ext.choseninlineresulthandler
     telegram.ext.conversationhandler
     telegram.ext.commandhandler

docs/source/telegram.inlinekeyboardbutton.rst

@@ -1,5 +1,5 @@
 telegram.inlinekeyboardbutton module
-===========================
+====================================
 
 .. automodule:: telegram.inlinekeyboardbutton
     :members:

docs/source/telegram.inlinekeyboardmarkup.rst

@@ -1,5 +1,5 @@
 telegram.inlinekeyboardmarkup module
-==========================
+====================================
 
 .. automodule:: telegram.inlinekeyboardmarkup
     :members:

docs/source/telegram.inlinequeryresultarticle.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultarticle module
-=================================
+========================================
 
 .. automodule:: telegram.inlinequeryresultarticle
     :members:

docs/source/telegram.inlinequeryresultaudio.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultaudio module
-=================================
+======================================
 
 .. automodule:: telegram.inlinequeryresultaudio
     :members:

docs/source/telegram.inlinequeryresultcachedaudio.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedaudio module
-=================================
+============================================
 
 .. automodule:: telegram.inlinequeryresultcachedaudio
     :members:

docs/source/telegram.inlinequeryresultcacheddocument.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcacheddocument module
-=================================
+===============================================
 
 .. automodule:: telegram.inlinequeryresultcacheddocument
     :members:

docs/source/telegram.inlinequeryresultcachedgif.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedgif module
-=================================
+==========================================
 
 .. automodule:: telegram.inlinequeryresultcachedgif
     :members:

docs/source/telegram.inlinequeryresultcachedmpeg4gif.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedmpeg4gif module
-=================================
+===============================================
 
 .. automodule:: telegram.inlinequeryresultcachedmpeg4gif
     :members:

docs/source/telegram.inlinequeryresultcachedphoto.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedphoto module
-=================================
+============================================
 
 .. automodule:: telegram.inlinequeryresultcachedphoto
     :members:

docs/source/telegram.inlinequeryresultcachedsticker.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedsticker module
-=================================
+==============================================
 
 .. automodule:: telegram.inlinequeryresultcachedsticker
     :members:

docs/source/telegram.inlinequeryresultcachedvideo.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedvideo module
-=================================
+============================================
 
 .. automodule:: telegram.inlinequeryresultcachedvideo
     :members:

docs/source/telegram.inlinequeryresultcachedvoice.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedvoice module
-=================================
+============================================
 
 .. automodule:: telegram.inlinequeryresultcachedvoice
     :members:

docs/source/telegram.inlinequeryresultcontact.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcontact module
-=================================
+========================================
 
 .. automodule:: telegram.inlinequeryresultcontact
     :members:

docs/source/telegram.inlinequeryresultdocument.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultdocument module
-=================================
+=========================================
 
 .. automodule:: telegram.inlinequeryresultdocument
     :members:

docs/source/telegram.inlinequeryresultgif.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultgif module
-=================================
+====================================
 
 .. automodule:: telegram.inlinequeryresultgif
     :members:

docs/source/telegram.inlinequeryresultlocation.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultlocation module
-=================================
+=========================================
 
 .. automodule:: telegram.inlinequeryresultlocation
     :members:

docs/source/telegram.inlinequeryresultmpeg4gif.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultmpeg4gif module
-=================================
+=========================================
 
 .. automodule:: telegram.inlinequeryresultmpeg4gif
     :members:

docs/source/telegram.inlinequeryresultphoto.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultphoto module
-=================================
+======================================
 
 .. automodule:: telegram.inlinequeryresultphoto
     :members:

docs/source/telegram.inlinequeryresultvenue.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultvenue module
-=================================
+======================================
 
 .. automodule:: telegram.inlinequeryresultvenue
     :members:

docs/source/telegram.inlinequeryresultvideo.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultvideo module
-=================================
+======================================
 
 .. automodule:: telegram.inlinequeryresultvideo
     :members:

docs/source/telegram.inlinequeryresultvoice.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultvoice module
-=================================
+======================================
 
 .. automodule:: telegram.inlinequeryresultvoice
     :members:

docs/source/telegram.nullhandler.rst

@@ -1,7 +0,0 @@
-telegram.nullhandler module
-===========================
-
-.. automodule:: telegram.nullhandler
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/telegram.rst

@@ -9,6 +9,8 @@ Submodules
    telegram.audio
    telegram.base
    telegram.bot
+   telegram.constants
+   telegram.contrib
    telegram.ext
    telegram.inlinequery
    telegram.inlinequeryresult
@@ -37,14 +39,12 @@ Submodules
    telegram.chataction
    telegram.contact
    telegram.document
-   telegram.emoji
    telegram.error
    telegram.forcereply
    telegram.chat
    telegram.inputfile
    telegram.location
    telegram.message
-   telegram.nullhandler
    telegram.photosize
    telegram.replykeyboardhide
    telegram.replykeyboardmarkup

telegram/bot.py

@@ -347,13 +347,13 @@ class Bot(TelegramObject):
 
         Args:
             chat_id: Unique identifier for the message recipient - Chat id.
-            audio Audio file to send. You can either pass a file_id as String to resend an audio
+            audio: Audio file to send. You can either pass a file_id as String to resend an audio
                 that is already on the Telegram servers, or upload a new audio file using
                 multipart/form-data.
             duration (Optional[int]): Duration of sent audio in seconds.
-            performer: Performer of sent audio. [Optional]
+            performer (Optional[str]): Performer of sent audio.
-            title: Title of sent audio. [Optional]
+            title (Optional[str]): Title of sent audio.
-            caption: Audio caption [Optional]
+            caption (Optional[str]): Audio caption
             disable_notification (Optional[bool]): Sends the message silently. iOS users will not
                 receive a notification, Android users will receive a notification with no sound.
             reply_to_message_id (Optional[int]): If the message is a reply, ID of the original
@@ -405,8 +405,8 @@ class Bot(TelegramObject):
             chat_id: Unique identifier for the message recipient - Chat id.
             document: File to send. You can either pass a file_id as String to resend a file that
                 is already on the Telegram servers, or upload a new file using multipart/form-data.
-            filename: File name that shows in telegram message (it is usefull when you send file
+            filename (Optional[str]): File name that shows in telegram message (it is usefull when
-                generated by temp module, for example). [Optional]
+                you send file generated by temp module, for example).
             caption (Optional[str]): Document caption (may also be used when resending documents by
                 file_id), 0-200 characters.
             disable_notification (Optional[bool]): Sends the message silently. iOS users will not
@@ -554,7 +554,7 @@ class Bot(TelegramObject):
                 that is already on the Telegram servers, or upload a new audio file using
                 multipart/form-data.
             duration (Optional[int]): Duration of sent audio in seconds.
-            caption: Voice caption [Optional]
+            caption (Optional[str]): Voice caption
             disable_notification (Optional[bool]): Sends the message silently. iOS users will not
                 receive a notification, Android users will receive a notification with no sound.
             reply_to_message_id (Optional[int]): If the message is a reply, ID of the original
@@ -777,6 +777,7 @@ class Bot(TelegramObject):
             chat_id: Unique identifier for the message recipient - Chat id.
             action: Type of action to broadcast. Choose one, depending on what the user is about to
                 receive:
+
                     - ChatAction.TYPING for text messages,
                     - ChatAction.UPLOAD_PHOTO for photos,
                     - ChatAction.UPLOAD_VIDEO for videos,
@@ -862,8 +863,8 @@ class Bot(TelegramObject):
 
         Args:
             user_id: Unique identifier of the target user.
-            offset (Optional[int]: Sequential number of the first photo to be returned. By default,
+            offset (Optional[int]): Sequential number of the first photo to be returned. By
-                all photos are returned.
+                default, all photos are returned.
             limit (Optional[int]): Limits the number of photos to be retrieved. Values between
                 1-100 are accepted. Defaults to 100.
             timeout (Optional[float]): If this value is specified, use it as the definitive timeout
@@ -960,7 +961,7 @@ class Bot(TelegramObject):
         Args:
             chat_id: Unique identifier for the target group or username of the target supergroup
                 (in the format @supergroupusername).
-          user_id: Unique identifier of the target user.
+            user_id: Unique identifier of the target user.
             timeout (Optional[float]): If this value is specified, use it as the definitive timeout
                 (in seconds) for urlopen() operations.
             **kwargs (dict): Arbitrary keyword arguments.

telegram/ext/callbackqueryhandler.py

@@ -39,7 +39,7 @@ class CallbackQueryHandler(Handler):
         pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``update_queue`` will be passed to the callback function. It will be the ``Queue``
             instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
-             be used to insert updates. Default is ``False``.
+            be used to insert updates. Default is ``False``.
         pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
             instance created by the ``Updater`` which can be used to schedule new jobs.

telegram/ext/choseninlineresulthandler.py

@@ -35,7 +35,7 @@ class ChosenInlineResultHandler(Handler):
         pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``update_queue`` will be passed to the callback function. It will be the ``Queue``
             instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
-             be used to insert updates. Default is ``False``.
+            be used to insert updates. Default is ``False``.
         pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
             instance created by the ``Updater`` which can be used to schedule new jobs.

telegram/ext/commandhandler.py

@@ -44,7 +44,7 @@ class CommandHandler(Handler):
         pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``update_queue`` will be passed to the callback function. It will be the ``Queue``
             instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
-             be used to insert updates. Default is ``False``.
+            be used to insert updates. Default is ``False``.
         pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
             instance created by the ``Updater`` which can be used to schedule new jobs.

telegram/ext/dispatcher.py

@@ -309,7 +309,7 @@ class Dispatcher(object):
             which handlers were added to the group defines the priority.
 
         Args:
-            handler (Handler): A Handler instance
+            handler (telegram.ext.Handler): A Handler instance
             group (Optional[int]): The group identifier. Default is 0
         """
 
@@ -330,7 +330,7 @@ class Dispatcher(object):
         Remove a handler from the specified group
 
         Args:
-            handler (Handler): A Handler instance
+            handler (telegram.ext.Handler): A Handler instance
             group (optional[object]): The group identifier. Default is 0
         """
         if handler in self.handlers[group]:

telegram/ext/handler.py

@@ -35,7 +35,7 @@ class Handler(object):
         pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``update_queue`` will be passed to the callback function. It will be the ``Queue``
             instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
-             be used to insert updates. Default is ``False``.
+            be used to insert updates. Default is ``False``.
         pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
             instance created by the ``Updater`` which can be used to schedule new jobs.
@@ -85,7 +85,7 @@ class Handler(object):
 
         Args:
             update (object): The update to be handled
-            dispatcher (Dispatcher): The dispatcher to collect optional args
+            dispatcher (telegram.ext.Dispatcher): The dispatcher to collect optional args
 
         """
         raise NotImplementedError
@@ -96,7 +96,7 @@ class Handler(object):
         handlers
 
         Args:
-            dispatcher (Dispatcher):
+            dispatcher (telegram.ext.Dispatcher):
         """
         optional_args = dict()
 

telegram/ext/inlinequeryhandler.py

@@ -38,7 +38,7 @@ class InlineQueryHandler(Handler):
         pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``update_queue`` will be passed to the callback function. It will be the ``Queue``
             instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
-             be used to insert updates. Default is ``False``.
+            be used to insert updates. Default is ``False``.
         pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
             instance created by the ``Updater`` which can be used to schedule new jobs.

telegram/ext/jobqueue.py

@@ -30,10 +30,10 @@ class JobQueue(object):
 
     Attributes:
         queue (PriorityQueue):
-        bot (Bot):
+        bot (telegram.Bot):
 
     Args:
-        bot (Bot): The bot instance that should be passed to the jobs
+        bot (telegram.Bot): The bot instance that should be passed to the jobs
 
     Deprecated: 5.2
         prevent_autostart (Optional[bool]): Thread does not start during initialisation.
@@ -60,7 +60,7 @@ class JobQueue(object):
         """Queue a new job.
 
         Args:
-            job (Job): The ``Job`` instance representing the new job
+            job (telegram.ext.Job): The ``Job`` instance representing the new job
             next_t (Optional[float]): Time in seconds in which the job should be executed first.
                 Defaults to ``job.interval``
 

telegram/ext/regexhandler.py

@@ -48,7 +48,7 @@ class RegexHandler(Handler):
         pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``update_queue`` will be passed to the callback function. It will be the ``Queue``
             instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
-             be used to insert updates. Default is ``False``.
+            be used to insert updates. Default is ``False``.
         pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
             instance created by the ``Updater`` which can be used to schedule new jobs.

telegram/ext/stringcommandhandler.py

@@ -40,7 +40,7 @@ class StringCommandHandler(Handler):
         pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``update_queue`` will be passed to the callback function. It will be the ``Queue``
             instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
-             be used to insert updates. Default is ``False``.
+            be used to insert updates. Default is ``False``.
         pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
             instance created by the ``Updater`` which can be used to schedule new jobs.

telegram/ext/stringregexhandler.py

@@ -47,7 +47,7 @@ class StringRegexHandler(Handler):
         pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``update_queue`` will be passed to the callback function. It will be the ``Queue``
             instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
-             be used to insert updates. Default is ``False``.
+            be used to insert updates. Default is ``False``.
         pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
             instance created by the ``Updater`` which can be used to schedule new jobs.

telegram/ext/typehandler.py

@@ -37,7 +37,7 @@ class TypeHandler(Handler):
         pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``update_queue`` will be passed to the callback function. It will be the ``Queue``
             instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
-             be used to insert updates. Default is ``False``.
+            be used to insert updates. Default is ``False``.
         pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
             instance created by the ``Updater`` which can be used to schedule new jobs.

telegram/inlinequeryresultcachedmpeg4gif.py

@@ -44,7 +44,7 @@ class InlineQueryResultCachedMpeg4Gif(InlineQueryResult):
         caption	(Optional[str]):
         reply_markup (Optional[:class:`telegram.InlineKeyboardMarkup`]):
         input_message_content (Optional[:class:`telegram.InputMessageContent`]):
-         **kwargs (dict): Arbitrary keyword arguments.
+        **kwargs (dict): Arbitrary keyword arguments.
 
     """
 

telegram/message.py

@@ -438,11 +438,10 @@ class Message(TelegramObject):
     def forward(self, chat_id, disable_notification=False):
         """Shortcut for
 
-            bot.forwardMessage(chat_id=chat_id,
+            >>> bot.forwardMessage(chat_id=chat_id,
-                               from_chat_id=update.message.chat_id,
+            ...                    from_chat_id=update.message.chat_id,
-                               disable_notification=disable_notification,
+            ...                    disable_notification=disable_notification,
-                               message_id=update.message.message_id)
+            ...                    message_id=update.message.message_id)
-
         """
         return self.bot.forwardMessage(
             chat_id=chat_id,
@@ -452,42 +451,48 @@ class Message(TelegramObject):
 
     def edit_text(self, *args, **kwargs):
         """
-        Shortcut for ``bot.editMessageText(chat_id=message.chat_id,
+        Shortcut for
-                                       message_id=message.message_id,
+
-                                       *args, **kwargs)``
+            >>> bot.editMessageText(chat_id=message.chat_id,
+            ...                     message_id=message.message_id,
+            ...                     *args, **kwargs)
 
         Note:
             You can only edit messages that the bot sent itself,
             therefore this method can only be used on the
-            return value of the bot.send_* family of methods.
+            return value of the ``bot.send_*`` family of methods.
         """
         return self.bot.edit_message_text(
             chat_id=self.chat_id, message_id=self.message_id, *args, **kwargs)
 
     def edit_caption(self, *args, **kwargs):
         """
-        Shortcut for ``bot.editMessageCaption(chat_id=message.chat_id,
+        Shortcut for
-                                              message_id=message.message_id,
+
-                                              *args, **kwargs)``
+            >>> bot.editMessageCaption(chat_id=message.chat_id,
+            ...                        message_id=message.message_id,
+            ...                        *args, **kwargs)
 
         Note:
             You can only edit messages that the bot sent itself,
             therefore this method can only be used on the
-            return value of the bot.send_* family of methods.
+            return value of the ``bot.send_*`` family of methods.
         """
         return self.bot.edit_message_caption(
             chat_id=self.chat_id, message_id=self.message_id, *args, **kwargs)
 
     def edit_reply_markup(self, *args, **kwargs):
         """
-        Shortcut for ``bot.editReplyMarkup(chat_id=message.chat_id,
+        Shortcut for
-                                           message_id=message.message_id,
+
-                                           *args, **kwargs)``
+            >>> bot.editReplyMarkup(chat_id=message.chat_id,
+            ...                     message_id=message.message_id,
+            ...                     *args, **kwargs)
 
         Note:
             You can only edit messages that the bot sent itself,
             therefore this method can only be used on the
-            return value of the bot.send_* family of methods.
+            return value of the ``bot.send_*`` family of methods.
         """
         return self.bot.edit_message_caption(
             chat_id=self.chat_id, message_id=self.message_id, *args, **kwargs)