Merge pull request #649 from python-telegram-bot/fix-docs

Fix some documentation stuff
[ci skip]

docs/source/conf.py

@@ -11,7 +11,6 @@
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
-
 import sys
 import os
 import shlex
@@ -25,7 +24,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+needs_sphinx = '1.5.4'  # fixes issues with autodoc-skip-member and napoleon
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -136,7 +135,7 @@ html_logo = 'ptb-logo-orange.png'
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-#html_favicon = None
+html_favicon = 'ptb-logo-orange.ico'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -289,3 +288,21 @@ texinfo_documents = [
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+# -- script stuff --------------------------------------------------------
+
+import inspect
+
+
+def autodoc_skip_member(app, what, name, obj, skip, options):
+    try:
+        if inspect.getmodule(obj).__name__.startswith('telegram') and inspect.isfunction(obj):
+            if name.lower() != name:
+                return True
+    except AttributeError:
+        pass
+    # Return None so napoleon can handle it
+
+
+def setup(app):
+    app.connect('autodoc-skip-member', autodoc_skip_member)

telegram/chat.py

@@ -41,7 +41,7 @@ class Chat(TelegramObject):
         username(Optional[str]):
         first_name(Optional[str]):
         last_name(Optional[str]):
-        bot (Optional[Bot]): The Bot to use for instance methods
+        bot (Optional[telegram.Bot]): The Bot to use for instance methods
         **kwargs (dict): Arbitrary keyword arguments.
 
     """

telegram/ext/jobqueue.py

@@ -166,7 +166,8 @@ class JobQueue(object):
             name (Optional[str]): The name of the new job. Defaults to ``callback.__name__``
 
         Returns:
-            Job: The new ``Job`` instance that has been added to the job queue.
+            telegram.ext.jobqueue.Job: The new ``Job`` instance that has been added to the
+                job queue.
 
         """
         job = Job(callback, repeat=False, context=context, name=name, job_queue=self)
@@ -201,7 +202,8 @@ class JobQueue(object):
             name (Optional[str]): The name of the new job. Defaults to ``callback.__name__``
 
         Returns:
-            Job: The new ``Job`` instance that has been added to the job queue.
+            telegram.ext.jobqueue.Job: The new ``Job`` instance that has been added to the
+                job queue.
 
         """
         job = Job(callback,
@@ -228,7 +230,8 @@ class JobQueue(object):
             name (Optional[str]): The name of the new job. Defaults to ``callback.__name__``
 
         Returns:
-            Job: The new ``Job`` instance that has been added to the job queue.
+            telegram.ext.jobqueue.Job: The new ``Job`` instance that has been added to the
+                job queue.
 
         """
         job = Job(callback,
@@ -366,7 +369,7 @@ class Job(object):
             job runs
         repeat (bool): If the job runs periodically or only once
         name (str): The name of this job
-        job_queue (JobQueue): The ``JobQueue`` this job belongs to
+        job_queue (telegram.ext.JobQueue): The ``JobQueue`` this job belongs to
         enabled (bool): Boolean property that decides if this job is currently active
 
     Args:

telegram/ext/typehandler.py

@@ -27,7 +27,7 @@ class TypeHandler(Handler):
     Handler class to handle updates of custom types.
 
     Args:
-        type (type): The ``type`` of updates this handler should process, as
+        type (class): The ``type`` of updates this handler should process, as
             determined by ``isinstance``
         callback (function): A function that takes ``bot, update`` as
             positional arguments. It will be called when the ``check_update``

telegram/ext/updater.py

@@ -59,9 +59,9 @@ class Updater(object):
         base_url (Optional[str]):
         workers (Optional[int]): Amount of threads in the thread pool for
             functions decorated with @run_async
-        bot (Optional[Bot]): A pre-initialized bot instance. If a pre-initizlied bot is used, it is
-            the user's responsibility to create it using a `Request` instance with a large enough
-            connection pool.
+        bot (Optional[telegram.Bot]): A pre-initialized bot instance. If a pre-initizlied bot is
+            used, it is the user's responsibility to create it using a `Request` instance with
+            a large enough connection pool.
         user_sig_handler (Optional[function]): Takes ``signum, frame`` as positional arguments.
             This will be called when a signal is received, defaults are (SIGINT, SIGTERM, SIGABRT)
             setable with Updater.idle(stop_signals=(signals))

telegram/inlinequery.py

@@ -40,7 +40,7 @@ class InlineQuery(TelegramObject):
         query (str):
         offset (str):
         location (optional[:class:`telegram.Location`]):
-        bot (Optional[Bot]): The Bot to use for instance methods
+        bot (Optional[telegram.Bot]): The Bot to use for instance methods
         **kwargs (dict): Arbitrary keyword arguments.
 
     """

telegram/inputfile.py

@@ -79,7 +79,7 @@ class InputFile(object):
     def headers(self):
         """
         Returns:
-            str:
+            str
         """
         return {'User-agent': USER_AGENT, 'Content-type': self.content_type}
 
@@ -87,14 +87,14 @@ class InputFile(object):
     def content_type(self):
         """
         Returns:
-            str:
+            str
         """
         return 'multipart/form-data; boundary=%s' % self.boundary
 
     def to_form(self):
         """
         Returns:
-            str:
+            str
         """
         form = []
         form_boundary = '--' + self.boundary
@@ -122,7 +122,7 @@ class InputFile(object):
     def _parse(form):
         """
         Returns:
-            str:
+            str
         """
         if sys.version_info > (3,):
             # on Python 3 form needs to be byte encoded

telegram/message.py

@@ -98,7 +98,7 @@ class Message(TelegramObject):
             about the invoice.
         successful_payment (:class:`telegram.SuccessfulPayment`): Message is a service message
             about a successful payment, information about the payment.
-        bot (Optional[Bot]): The Bot to use for instance methods
+        bot (Optional[telegram.Bot]): The Bot to use for instance methods
 
     Deprecated: 4.0
         new_chat_participant (:class:`telegram.User`): Use `new_chat_member`
@@ -106,7 +106,6 @@ class Message(TelegramObject):
 
         left_chat_participant  (:class:`telegram.User`): Use `left_chat_member`
         instead.
-
     """
 
     def __init__(self,

telegram/replykeyboardremove.py

@@ -31,9 +31,11 @@ class ReplyKeyboardRemove(ReplyMarkup):
     Args:
         selective (Optional[bool]): Use this parameter if you want to remove the keyboard for
             specific users only. Targets:
-                1) users that are @mentioned in the text of the Message object;
-                2) if the bot's message is a reply (has reply_to_message_id), sender of the
-                    original message.
+
+            - users that are @mentioned in the text of the Message object
+            - if the bot's message is a reply (has reply_to_message_id), sender of the
+              original message.
+
         **kwargs: Arbitrary keyword arguments.
 
     """

telegram/user.py

@@ -43,7 +43,7 @@ class User(TelegramObject):
         last_name (Optional[str]): User's or bot's last name
         username (Optional[str]): User's or bot's username
         language_code (Optional[str]): IETF language tag of the user's language
-        bot (Optional[Bot]): The Bot to use for instance methods
+        bot (Optional[telegram.Bot]): The Bot to use for instance methods
     """
 
     def __init__(self,