Sphinx restructuring: Now builds PDF and better HTML docs (python-telegram-bot#449)

jh0ker · web-flow · commit aa3ca3883735 · 2016-11-01T06:53:51.000+01:00
* 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
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -209,6 +209,9 @@
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
+    'preamble': '''\\setcounter{tocdepth}{2}
+\\usepackage{enumitem}
+\\setlistdepth{99}''',
 # The paper size ('letterpaper' or 'a4paper').
 #'papersize': 'letterpaper',
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -10,7 +10,7 @@ Contents:
    telegram
 
 .. toctree::
-   :maxdepth: 2
+   telegram
 
 
 
diff --git a/docs/source/modules.rst b/docs/source/modules.rst
diff --git a/docs/source/telegram.contrib.rst b/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:
diff --git a/docs/source/telegram.ext.rst b/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
diff --git a/docs/source/telegram.inlinekeyboardbutton.rst b/docs/source/telegram.inlinekeyboardbutton.rst
@@ -1,5 +1,5 @@
 telegram.inlinekeyboardbutton module
-===========================
+====================================
 
 .. automodule:: telegram.inlinekeyboardbutton
     :members:
diff --git a/docs/source/telegram.inlinekeyboardmarkup.rst b/docs/source/telegram.inlinekeyboardmarkup.rst
@@ -1,5 +1,5 @@
 telegram.inlinekeyboardmarkup module
-==========================
+====================================
 
 .. automodule:: telegram.inlinekeyboardmarkup
     :members:
diff --git a/docs/source/telegram.inlinequeryresultarticle.rst b/docs/source/telegram.inlinequeryresultarticle.rst
@@ -1,5 +1,5 @@
 telegram.inlinequeryresultarticle module
-=================================
+========================================
 
 .. automodule:: telegram.inlinequeryresultarticle
     :members:
diff --git a/docs/source/telegram.inlinequeryresultaudio.rst b/docs/source/telegram.inlinequeryresultaudio.rst
@@ -1,5 +1,5 @@
 telegram.inlinequeryresultaudio module
-=================================
+======================================
 
 .. automodule:: telegram.inlinequeryresultaudio
     :members:
diff --git a/docs/source/telegram.inlinequeryresultcachedaudio.rst b/docs/source/telegram.inlinequeryresultcachedaudio.rst
@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedaudio module
-=================================
+============================================
 
 .. automodule:: telegram.inlinequeryresultcachedaudio
     :members:
diff --git a/docs/source/telegram.inlinequeryresultcacheddocument.rst b/docs/source/telegram.inlinequeryresultcacheddocument.rst
@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcacheddocument module
-=================================
+===============================================
 
 .. automodule:: telegram.inlinequeryresultcacheddocument
     :members:
diff --git a/docs/source/telegram.inlinequeryresultcachedgif.rst b/docs/source/telegram.inlinequeryresultcachedgif.rst
@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedgif module
-=================================
+==========================================
 
 .. automodule:: telegram.inlinequeryresultcachedgif
     :members:
diff --git a/docs/source/telegram.inlinequeryresultcachedmpeg4gif.rst b/docs/source/telegram.inlinequeryresultcachedmpeg4gif.rst
@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedmpeg4gif module
-=================================
+===============================================
 
 .. automodule:: telegram.inlinequeryresultcachedmpeg4gif
     :members:
diff --git a/docs/source/telegram.inlinequeryresultcachedphoto.rst b/docs/source/telegram.inlinequeryresultcachedphoto.rst
@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedphoto module
-=================================
+============================================
 
 .. automodule:: telegram.inlinequeryresultcachedphoto
     :members:
diff --git a/docs/source/telegram.inlinequeryresultcachedsticker.rst b/docs/source/telegram.inlinequeryresultcachedsticker.rst
@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedsticker module
-=================================
+==============================================
 
 .. automodule:: telegram.inlinequeryresultcachedsticker
     :members:
diff --git a/docs/source/telegram.inlinequeryresultcachedvideo.rst b/docs/source/telegram.inlinequeryresultcachedvideo.rst
@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedvideo module
-=================================
+============================================
 
 .. automodule:: telegram.inlinequeryresultcachedvideo
     :members:
diff --git a/docs/source/telegram.inlinequeryresultcachedvoice.rst b/docs/source/telegram.inlinequeryresultcachedvoice.rst
@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedvoice module
-=================================
+============================================
 
 .. automodule:: telegram.inlinequeryresultcachedvoice
     :members:
diff --git a/docs/source/telegram.inlinequeryresultcontact.rst b/docs/source/telegram.inlinequeryresultcontact.rst
@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcontact module
-=================================
+========================================
 
 .. automodule:: telegram.inlinequeryresultcontact
     :members:
diff --git a/docs/source/telegram.inlinequeryresultdocument.rst b/docs/source/telegram.inlinequeryresultdocument.rst
@@ -1,5 +1,5 @@
 telegram.inlinequeryresultdocument module
-=================================
+=========================================
 
 .. automodule:: telegram.inlinequeryresultdocument
     :members:
diff --git a/docs/source/telegram.inlinequeryresultgif.rst b/docs/source/telegram.inlinequeryresultgif.rst
@@ -1,5 +1,5 @@
 telegram.inlinequeryresultgif module
-=================================
+====================================
 
 .. automodule:: telegram.inlinequeryresultgif
     :members:
diff --git a/docs/source/telegram.inlinequeryresultlocation.rst b/docs/source/telegram.inlinequeryresultlocation.rst
@@ -1,5 +1,5 @@
 telegram.inlinequeryresultlocation module
-=================================
+=========================================
 
 .. automodule:: telegram.inlinequeryresultlocation
     :members:
diff --git a/docs/source/telegram.inlinequeryresultmpeg4gif.rst b/docs/source/telegram.inlinequeryresultmpeg4gif.rst
@@ -1,5 +1,5 @@
 telegram.inlinequeryresultmpeg4gif module
-=================================
+=========================================
 
 .. automodule:: telegram.inlinequeryresultmpeg4gif
     :members:
diff --git a/docs/source/telegram.inlinequeryresultphoto.rst b/docs/source/telegram.inlinequeryresultphoto.rst
@@ -1,5 +1,5 @@
 telegram.inlinequeryresultphoto module
-=================================
+======================================
 
 .. automodule:: telegram.inlinequeryresultphoto
     :members:
diff --git a/docs/source/telegram.inlinequeryresultvenue.rst b/docs/source/telegram.inlinequeryresultvenue.rst
@@ -1,5 +1,5 @@
 telegram.inlinequeryresultvenue module
-=================================
+======================================
 
 .. automodule:: telegram.inlinequeryresultvenue
     :members:
diff --git a/docs/source/telegram.inlinequeryresultvideo.rst b/docs/source/telegram.inlinequeryresultvideo.rst
@@ -1,5 +1,5 @@
 telegram.inlinequeryresultvideo module
-=================================
+======================================
 
 .. automodule:: telegram.inlinequeryresultvideo
     :members:
diff --git a/docs/source/telegram.inlinequeryresultvoice.rst b/docs/source/telegram.inlinequeryresultvoice.rst
@@ -1,5 +1,5 @@
 telegram.inlinequeryresultvoice module
-=================================
+======================================
 
 .. automodule:: telegram.inlinequeryresultvoice
     :members:
diff --git a/docs/source/telegram.nullhandler.rst b/docs/source/telegram.nullhandler.rst
diff --git a/docs/source/telegram.rst b/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
diff --git a/telegram/bot.py b/telegram/bot.py
@@ -347,13 +347,13 @@ def sendAudio(self,
 
         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]
-            title: Title of sent audio. [Optional]
-            caption: Audio caption [Optional]
+            performer (Optional[str]): Performer of sent audio.
+            title (Optional[str]): Title of sent audio.
+            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 @@ def sendDocument(self,
             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
-                generated by temp module, for example). [Optional]
+            filename (Optional[str]): File name that shows in telegram message (it is usefull when
+                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 @@ def sendVoice(self,
                 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 @@ def sendChatAction(self, chat_id, action, **kwargs):
             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 @@ def getUserProfilePhotos(self, user_id, offset=None, limit=100, timeout=None, **
 
         Args:
             user_id: Unique identifier of the target user.
-            offset (Optional[int]: Sequential number of the first photo to be returned. By default,
-                all photos are returned.
+            offset (Optional[int]): Sequential number of the first photo to be returned. By
+                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 @@ def unbanChatMember(self, chat_id, user_id, timeout=None, **kwargs):
         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.
diff --git a/telegram/ext/callbackqueryhandler.py b/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.
diff --git a/telegram/ext/choseninlineresulthandler.py b/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.
diff --git a/telegram/ext/commandhandler.py b/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.
diff --git a/telegram/ext/dispatcher.py b/telegram/ext/dispatcher.py
@@ -309,7 +309,7 @@ def add_handler(self, handler, group=DEFAULT_GROUP):
             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 @@ def remove_handler(self, handler, group=DEFAULT_GROUP):
         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]:
diff --git a/telegram/ext/handler.py b/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 @@ def handle_update(self, update, dispatcher):
 
         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 @@ def collect_optional_args(self, dispatcher, update=None):
         handlers
 
         Args:
-            dispatcher (Dispatcher):
+            dispatcher (telegram.ext.Dispatcher):
         """
         optional_args = dict()
 
diff --git a/telegram/ext/inlinequeryhandler.py b/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.
diff --git a/telegram/ext/jobqueue.py b/telegram/ext/jobqueue.py
diff --git a/telegram/ext/regexhandler.py b/telegram/ext/regexhandler.py
diff --git a/telegram/ext/stringcommandhandler.py b/telegram/ext/stringcommandhandler.py
diff --git a/telegram/ext/stringregexhandler.py b/telegram/ext/stringregexhandler.py
diff --git a/telegram/ext/typehandler.py b/telegram/ext/typehandler.py
diff --git a/telegram/inlinequeryresultcachedmpeg4gif.py b/telegram/inlinequeryresultcachedmpeg4gif.py
diff --git a/telegram/message.py b/telegram/message.py
