Documentation fixes (#1348)

* Clarify InlineKeyboardButton callback-data docstring

Fixes #1267

* Improve documentation slightly

- Prettier changelog
- Link to examples on frontpage
- Link to wiki on frontpage
- Put telegram.ext in own sidebar thingy

* Improve ext.Filters documentation

Superseeds #1089

- Remove `:obj:Filter` as it's pretty obvious that it's a filter since it's in this module. It also made the html output about 1/3 times longer to scroll through.
- Add an __all__ to reorder so Filter is at the top instead of BaseFilter
- Add a proper docstring for document that documents the attributes (this is the #1089 part)
- Also fix a couple of grammar errors.

* Fix indentation in telegram.rst

* Add `git describe --long --tags` to the `python -m telegram` output

* Use admonition for examples to make them *pop* better

* Remove automodule telegram

Sphinx was whining a lot and it doesn't actually seem to be needed in any way?

* Fix Filters.document docstring per CR

Co-Authored-By: jsmnbom <jsmnbom@gmail.com>

* Fix spelling error in docs index

Co-Authored-By: jsmnbom <jsmnbom@gmail.com>

* Setting needs_sphinx to 1.7.9

so we don't have more issues with incongruent versions

* Fixed last warnings

* Make pre-commit happy

CHANGES.rst

@@ -1,6 +1,6 @@
-=======
+=========
-Changes
+Changelog
-=======
+=========
 
 Version 12.0.0b1
 ================
@@ -119,11 +119,9 @@ Internal improvements
 - Allow pypy to fail in CI.
 - Remove the last CamelCase CheckUpdate methods from the handlers we missed earlier.
 
-Pre-2019 (up and including to version 11.1.0)
+Version 11.1.0
-=============================================
+==============
-
+*Released 2018-09-01*
-**2018-09-01**
-*Released 11.1.0*
 
 Fixes and updates for Telegram Passport: (`#1198`_)
 
@@ -137,8 +135,9 @@ Fixes and updates for Telegram Passport: (`#1198`_)
 
 .. _`#1198`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1198
 
-**2018-08-29**
+Version 11.0.0
-*Released 11.0.0*
+==============
+*Released 2018-08-29*
 
 Fully support Bot API version 4.0!
 (also some bugfixes :))
@@ -193,8 +192,9 @@ Non Bot API 4.0 changes:
 .. _`#1184`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1184
 .. _`our telegram passport wiki page`: https://git.io/fAvYd
 
-**2018-05-02**
+Version 10.1.0
-*Released 10.1.0*
+==============
+*Released 2018-05-02*
 
 Fixes changing previous behaviour:
 
@@ -220,8 +220,9 @@ Fixes:
 .. _`#1096`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1096
 .. _`#1099`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1099
 
-**2018-04-17**
+Version 10.0.2
-*Released 10.0.2*
+==============
+*Released 2018-04-17*
 
 Important fix:
 
@@ -252,8 +253,9 @@ Fixes:
 .. _`#1076`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1076
 .. _`#1071`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1071
 
-**2018-03-05**
+Version 10.0.1
-*Released 10.0.1*
+==============
+*Released 2018-03-05*
 
 Fixes:
 
@@ -263,8 +265,9 @@ Fixes:
 .. _`#1032`: https://github.com/python-telegram-bot/python-telegram-bot/pull/826
 .. _`#912`: https://github.com/python-telegram-bot/python-telegram-bot/pull/826
 
-**2018-03-02**
+Version 10.0.0
-*Released 10.0.0*
+==============
+*Released 2018-03-02*
 
 Non backward compatabile changes and changed defaults
 
@@ -329,8 +332,9 @@ Changes
 .. _`#1019`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1019
 .. _`#1020`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1020
 
-**2017-12-08**
+Version 9.0.0
-*Released 9.0.0*
+=============
+*Released 2017-12-08*
 
 Breaking changes (possibly)
 
@@ -355,15 +359,17 @@ Changes
 .. _`#694`: https://github.com/python-telegram-bot/python-telegram-bot/pull/694
 .. _`#870`: https://github.com/python-telegram-bot/python-telegram-bot/pull/870
 
-**2017-10-15**
+Version 8.1.1
-*Released 8.1.1*
+=============
+*Released 2017-10-15*
 
 - Fix Commandhandler crashing on single character messages (PR `#873`_).
 
 .. _`#873`: https://github.com/python-telegram-bot/python-telegram-bot/pull/871
 
-**2017-10-14**
+Version 8.1.0
-*Released 8.1.0*
+=============
+*Released 2017-10-14*
 
 New features
 - Support Bot API 3.4 (PR `#865`_).
@@ -380,8 +386,9 @@ Changes
 .. _`#865`: https://github.com/python-telegram-bot/python-telegram-bot/pull/865
 .. _`#869`: https://github.com/python-telegram-bot/python-telegram-bot/pull/869
 
-**2017-09-01**
+Version 8.0.0
-*Released 8.0.0*
+=============
+*Released 2017-09-01*
 
 New features
 
@@ -422,14 +429,16 @@ Changes
 .. _`#793`: https://github.com/python-telegram-bot/python-telegram-bot/pull/793
 .. _`#810`: https://github.com/python-telegram-bot/python-telegram-bot/pull/810
 
-**2017-07-28**
+Version 7.0.1
-*Released 7.0.1*
+===============
+*Released 2017-07-28*
 
 - Fix TypeError exception in RegexHandler (PR #751).
 - Small documentation fix (PR #749).
 
-**2017-07-25**
+Version 7.0.0
-*Released 7.0.0*
+=============
+*Released 2017-07-25*
 
 - Fully support Bot API 3.2.
 - New filters for handling messages from specific chat/user id (PR #677).
@@ -447,6 +456,9 @@ Changes
 - Improved documentation.
 - Improved unitests.
 
+Pre-version 7.0
+===============
+
 **2017-06-18**
 
 *Released 6.1.0*

docs/requirements-docs.txt

@@ -1,3 +1,3 @@
-sphinx>=1.5.4
+sphinx>=1.7.9
 sphinx_rtd_theme
 sphinx-pypi-upload

docs/source/changelog.rst

@@ -0,0 +1 @@
+.. include:: ../../CHANGES.rst

docs/source/conf.py

@@ -24,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.5.4'  # fixes issues with autodoc-skip-member and napoleon
+needs_sphinx = '1.7.9'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -289,6 +289,10 @@ texinfo_documents = [
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
 
+# Napoleon stuff
+
+napoleon_use_admonition_for_examples = True
+
 # -- script stuff --------------------------------------------------------
 
 

docs/source/index.rst

@@ -6,8 +6,23 @@
 Welcome to Python Telegram Bot's documentation!
 ===============================================
 
-Below you can find the documentation for the python-telegram-bot library. except for the .ext package most of the
+Guides and tutorials
-objects in the package reflect the types as defined by the `telegram bot api <https://core.telegram.org/bots/api>`_.
+====================
+
+If you're just starting out with the library, we recommend following our `"Your first Bot" <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions-%E2%80%93-Your-first-Bot>`_ tutorial that you can find on our `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki>`_.
+On our wiki you will also find guides like how to use handlers, webhooks, emoji, proxies and much more.
+
+Examples
+========
+
+A great way to learn is by looking at examples. Ours can be found at our `github in the examples folder <https://github.com/python-telegram-bot/python-telegram-bot/tree/master/examples>`_.
+
+
+Reference
+=========
+
+Below you can find a reference of all the classes and methods in python-telegram-bot.
+Apart from the telegram.ext package the objects should reflect the types defined in the `official telegram bot api documentation <https://core.telegram.org/bots/api>`_
 
 .. toctree::
    telegram
@@ -15,13 +30,9 @@ objects in the package reflect the types as defined by the `telegram bot api <ht
 Changelog
 ---------
 
-.. include:: ../../CHANGES.rst
+.. toctree::
+   :maxdepth: 2
 
-Indices and tables
+   changelog
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
 
 

docs/source/telegram.rst

@@ -1,10 +1,11 @@
+.. include:: telegram.ext.rst
+
+
 telegram package
 ================
 
 .. toctree::
 
-   telegram.ext
-   telegram.utils
     telegram.animation
     telegram.audio
     telegram.bot
@@ -137,12 +138,8 @@ Passport
     telegram.encryptedpassportelement
     telegram.encryptedcredentials
 
+telegram.utils
+--------------
 
-Module contents
+.. toctree::
----------------
+    telegram.utils
-
-.. automodule:: telegram
-    :members:
-    :undoc-members:
-    :show-inheritance:
-    :noindex:

telegram/__main__.py

@@ -17,15 +17,28 @@
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 import sys
+import subprocess
 
 import certifi
 import future
 
+
 from . import __version__ as telegram_ver
 
 
+def _git_revision():
+    try:
+        output = subprocess.check_output(["git", "describe", "--long", "--tags"],
+                                         stderr=subprocess.STDOUT)
+    except (subprocess.SubprocessError, OSError):
+        return None
+    return output.decode().strip()
+
+
 def print_ver_info():
-    print('python-telegram-bot {0}'.format(telegram_ver))
+    git_revision = _git_revision()
+    print('python-telegram-bot {0}'.format(telegram_ver) + (' ({0})'.format(git_revision)
+                                                            if git_revision else ''))
     print('certifi {0}'.format(certifi.__version__))
     print('future {0}'.format(future.__version__))
     print('Python {0}'.format(sys.version.replace('\n', ' ')))

telegram/ext/dispatcher.py

@@ -52,7 +52,7 @@ def run_async(func):
 
     Warning:
         If you're using @run_async you cannot rely on adding custom attributes to
-        :class:`telegram.ext.CallbackContext`s. See its docs for more info.
+        :class:`telegram.ext.CallbackContext`. See its docs for more info.
     """
 
     @wraps(func)
@@ -214,7 +214,7 @@ class Dispatcher(object):
 
         Warning:
             If you're using @run_async you cannot rely on adding custom attributes to
-            :class:`telegram.ext.CallbackContext`s. See its docs for more info.
+            :class:`telegram.ext.CallbackContext`. See its docs for more info.
 
         Args:
             func (:obj:`callable`): The function to run in the thread.

telegram/ext/filters.py

@@ -24,6 +24,8 @@ from future.utils import string_types
 
 from telegram import Chat
 
+__all__ = ['Filters', 'BaseFilter', 'InvertedFilter', 'MergedFilter']
+
 
 class BaseFilter(object):
     """Base class for all Message Filters.
@@ -213,7 +215,7 @@ class Filters(object):
             return True
 
     all = _All()
-    """:obj:`Filter`: All Messages."""
+    """All Messages."""
 
     class _Text(BaseFilter):
         name = 'Filters.text'
@@ -222,7 +224,7 @@ class Filters(object):
             return bool(message.text and not message.text.startswith('/'))
 
     text = _Text()
-    """:obj:`Filter`: Text Messages."""
+    """Text Messages."""
 
     class _Command(BaseFilter):
         name = 'Filters.command'
@@ -231,7 +233,7 @@ class Filters(object):
             return bool(message.text and message.text.startswith('/'))
 
     command = _Command()
-    """:obj:`Filter`: Messages starting with ``/``."""
+    """Messages starting with ``/``."""
 
     class regex(BaseFilter):
         """
@@ -276,7 +278,7 @@ class Filters(object):
             return bool(message.reply_to_message)
 
     reply = _Reply()
-    """:obj:`Filter`: Messages that are a reply to another message."""
+    """Messages that are a reply to another message."""
 
     class _Audio(BaseFilter):
         name = 'Filters.audio'
@@ -285,7 +287,7 @@ class Filters(object):
             return bool(message.audio)
 
     audio = _Audio()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Audio`."""
+    """Messages that contain :class:`telegram.Audio`."""
 
     class _Document(BaseFilter):
         name = 'Filters.document'
@@ -299,7 +301,7 @@ class Filters(object):
                 The user can manipulate the mime-type of a message and
                     send media with wrong types that don't fit to this handler.
 
-            Examples:
+            Example:
                 Filters.documents.category('audio/') returnes `True` for all types
                 of audio sent as file, for example 'audio/mpeg' or 'audio/x-wav'
             """
@@ -332,8 +334,8 @@ class Filters(object):
                 The user can manipulate the mime-type of a message and
                     send media with wrong types that don't fit to this handler.
 
-            Examples:
+            Example:
-                Filters.documents.mime_type('audio/mpeg') filters all audio in mp3 format.
+                ``Filters.documents.mime_type('audio/mpeg')`` filters all audio in mp3 format.
             """
 
             def __init__(self, mimetype):
@@ -369,7 +371,91 @@ class Filters(object):
             return bool(message.document)
 
     document = _Document()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Document`."""
+    """
+    Subset for messages containing a document/file.
+
+    Examples:
+        Use these filters like: ``Filters.document.mp3``,
+        ``Filters.document.mime_type("text/plain")`` etc. Or use just
+        ``Filters.document`` for all document messages.
+
+    Attributes:
+        category: This Filter filters documents by their category in the mime-type attribute.
+
+            Example:
+                ``Filters.documents.category('audio/')`` filters all types
+                of audio sent as file, for example 'audio/mpeg' or 'audio/x-wav'. The following
+                attributes can be used as a shortcut like: ``Filters.document.audio``
+
+        application:
+        audio:
+        image:
+        video:
+        text:
+        mime_type: This Filter filters documents by their mime-type attribute.
+
+            Example:
+                ``Filters.documents.mime_type('audio/mpeg')`` filters all audio in mp3 format. The
+                following attributes can be used as a shortcut like: ``Filters.document.jpg``
+        apk:
+        doc:
+        docx:
+        exe:
+        gif:
+        jpg:
+        mp3:
+        pdf:
+        py:
+        svg:
+        txt:
+        targz:
+        wav:
+        xml:
+        zip:
+        category: This Filter filters documents by their category in the mime-type attribute
+
+            Note:
+                This Filter only filters by the mime_type of the document,
+                it doesn't check the validity of the document.
+                The user can manipulate the mime-type of a message and
+                send media with wrong types that don't fit to this handler.
+
+            Example:
+                ``Filters.documents.category('audio/')`` filters all types
+                of audio sent as file, for example 'audio/mpeg' or 'audio/x-wav'
+        application: Same as ``Filters.document.category("application")``.
+        audio: Same as ``Filters.document.category("audio")``.
+        image: Same as ``Filters.document.category("image")``.
+        video: Same as ``Filters.document.category("video")``.
+        text: Same as ``Filters.document.category("text")``.
+        mime_type: This Filter filters documents by their mime-type attribute
+
+            Note:
+                This Filter only filters by the mime_type of the document,
+                it doesn't check the validity of document.
+
+                The user can manipulate the mime-type of a message and
+                send media with wrong types that don't fit to this handler.
+
+            Example:
+                ``Filters.documents.mime_type('audio/mpeg')`` filters all audio in mp3 format.
+        apk: Same as ``Filters.document.mime_type("application/vnd.android.package-archive")``-
+        doc: Same as ``Filters.document.mime_type("application/msword")``-
+        docx: Same as ``Filters.document.mime_type("application/vnd.openxmlformats-\
+officedocument.wordprocessingml.document")``-
+        exe: Same as ``Filters.document.mime_type("application/x-ms-dos-executable")``-
+        gif: Same as ``Filters.document.mime_type("video/mp4")``-
+        jpg: Same as ``Filters.document.mime_type("image/jpeg")``-
+        mp3: Same as ``Filters.document.mime_type("audio/mpeg")``-
+        pdf: Same as ``Filters.document.mime_type("application/pdf")``-
+        py: Same as ``Filters.document.mime_type("text/x-python")``-
+        svg: Same as ``Filters.document.mime_type("image/svg+xml")``-
+        txt: Same as ``Filters.document.mime_type("text/plain")``-
+        targz: Same as ``Filters.document.mime_type("application/x-compressed-tar")``-
+        wav: Same as ``Filters.document.mime_type("audio/x-wav")``-
+        xml: Same as ``Filters.document.mime_type("application/xml")``-
+        zip: Same as ``Filters.document.mime_type("application/zip")``-
+    """
 
     class _Animation(BaseFilter):
         name = 'Filters.animation'
@@ -378,7 +464,7 @@ class Filters(object):
             return bool(message.animation)
 
     animation = _Animation()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Animation`."""
+    """Messages that contain :class:`telegram.Animation`."""
 
     class _Photo(BaseFilter):
         name = 'Filters.photo'
@@ -387,7 +473,7 @@ class Filters(object):
             return bool(message.photo)
 
     photo = _Photo()
-    """:obj:`Filter`: Messages that contain :class:`telegram.PhotoSize`."""
+    """Messages that contain :class:`telegram.PhotoSize`."""
 
     class _Sticker(BaseFilter):
         name = 'Filters.sticker'
@@ -396,7 +482,7 @@ class Filters(object):
             return bool(message.sticker)
 
     sticker = _Sticker()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Sticker`."""
+    """Messages that contain :class:`telegram.Sticker`."""
 
     class _Video(BaseFilter):
         name = 'Filters.video'
@@ -405,7 +491,7 @@ class Filters(object):
             return bool(message.video)
 
     video = _Video()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Video`."""
+    """Messages that contain :class:`telegram.Video`."""
 
     class _Voice(BaseFilter):
         name = 'Filters.voice'
@@ -414,7 +500,7 @@ class Filters(object):
             return bool(message.voice)
 
     voice = _Voice()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Voice`."""
+    """Messages that contain :class:`telegram.Voice`."""
 
     class _VideoNote(BaseFilter):
         name = 'Filters.video_note'
@@ -423,7 +509,7 @@ class Filters(object):
             return bool(message.video_note)
 
     video_note = _VideoNote()
-    """:obj:`Filter`: Messages that contain :class:`telegram.VideoNote`."""
+    """Messages that contain :class:`telegram.VideoNote`."""
 
     class _Contact(BaseFilter):
         name = 'Filters.contact'
@@ -432,7 +518,7 @@ class Filters(object):
             return bool(message.contact)
 
     contact = _Contact()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Contact`."""
+    """Messages that contain :class:`telegram.Contact`."""
 
     class _Location(BaseFilter):
         name = 'Filters.location'
@@ -441,7 +527,7 @@ class Filters(object):
             return bool(message.location)
 
     location = _Location()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Location`."""
+    """Messages that contain :class:`telegram.Location`."""
 
     class _Venue(BaseFilter):
         name = 'Filters.venue'
@@ -450,7 +536,7 @@ class Filters(object):
             return bool(message.venue)
 
     venue = _Venue()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Venue`."""
+    """Messages that contain :class:`telegram.Venue`."""
 
     class _StatusUpdate(BaseFilter):
         """Subset for messages containing a status update.
@@ -469,7 +555,7 @@ class Filters(object):
                 return bool(message.new_chat_members)
 
         new_chat_members = _NewChatMembers()
-        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.new_chat_members`."""
+        """Messages that contain :attr:`telegram.Message.new_chat_members`."""
 
         class _LeftChatMember(BaseFilter):
             name = 'Filters.status_update.left_chat_member'
@@ -478,7 +564,7 @@ class Filters(object):
                 return bool(message.left_chat_member)
 
         left_chat_member = _LeftChatMember()
-        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.left_chat_member`."""
+        """Messages that contain :attr:`telegram.Message.left_chat_member`."""
 
         class _NewChatTitle(BaseFilter):
             name = 'Filters.status_update.new_chat_title'
@@ -487,7 +573,7 @@ class Filters(object):
                 return bool(message.new_chat_title)
 
         new_chat_title = _NewChatTitle()
-        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.new_chat_title`."""
+        """Messages that contain :attr:`telegram.Message.new_chat_title`."""
 
         class _NewChatPhoto(BaseFilter):
             name = 'Filters.status_update.new_chat_photo'
@@ -496,7 +582,7 @@ class Filters(object):
                 return bool(message.new_chat_photo)
 
         new_chat_photo = _NewChatPhoto()
-        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.new_chat_photo`."""
+        """Messages that contain :attr:`telegram.Message.new_chat_photo`."""
 
         class _DeleteChatPhoto(BaseFilter):
             name = 'Filters.status_update.delete_chat_photo'
@@ -505,7 +591,7 @@ class Filters(object):
                 return bool(message.delete_chat_photo)
 
         delete_chat_photo = _DeleteChatPhoto()
-        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.delete_chat_photo`."""
+        """Messages that contain :attr:`telegram.Message.delete_chat_photo`."""
 
         class _ChatCreated(BaseFilter):
             name = 'Filters.status_update.chat_created'
@@ -515,7 +601,7 @@ class Filters(object):
                             or message.channel_chat_created)
 
         chat_created = _ChatCreated()
-        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.group_chat_created`,
+        """Messages that contain :attr:`telegram.Message.group_chat_created`,
             :attr: `telegram.Message.supergroup_chat_created` or
             :attr: `telegram.Message.channel_chat_created`."""
 
@@ -526,7 +612,7 @@ class Filters(object):
                 return bool(message.migrate_from_chat_id or message.migrate_to_chat_id)
 
         migrate = _Migrate()
-        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.migrate_from_chat_id` or
+        """Messages that contain :attr:`telegram.Message.migrate_from_chat_id` or
             :attr: `telegram.Message.migrate_to_chat_id`."""
 
         class _PinnedMessage(BaseFilter):
@@ -536,7 +622,7 @@ class Filters(object):
                 return bool(message.pinned_message)
 
         pinned_message = _PinnedMessage()
-        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.pinned_message`."""
+        """Messages that contain :attr:`telegram.Message.pinned_message`."""
 
         class _ConnectedWebsite(BaseFilter):
             name = 'Filters.status_update.connected_website'
@@ -545,7 +631,7 @@ class Filters(object):
                 return bool(message.connected_website)
 
         connected_website = _ConnectedWebsite()
-        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.connected_website`."""
+        """Messages that contain :attr:`telegram.Message.connected_website`."""
 
         name = 'Filters.status_update'
 
@@ -564,24 +650,24 @@ class Filters(object):
         ``Filters.status_update`` for all status update messages.
 
     Attributes:
-        chat_created (:obj:`Filter`): Messages that contain
+        chat_created: Messages that contain
             :attr:`telegram.Message.group_chat_created`,
             :attr:`telegram.Message.supergroup_chat_created` or
             :attr:`telegram.Message.channel_chat_created`.
-        delete_chat_photo (:obj:`Filter`): Messages that contain
+        delete_chat_photo: Messages that contain
             :attr:`telegram.Message.delete_chat_photo`.
-        left_chat_member (:obj:`Filter`): Messages that contain
+        left_chat_member: Messages that contain
             :attr:`telegram.Message.left_chat_member`.
-        migrate (:obj:`Filter`): Messages that contain
+        migrate: Messages that contain
             :attr:`telegram.Message.migrate_from_chat_id` or
             :attr: `telegram.Message.migrate_from_chat_id`.
-        new_chat_members (:obj:`Filter`): Messages that contain
+        new_chat_members: Messages that contain
             :attr:`telegram.Message.new_chat_members`.
-        new_chat_photo (:obj:`Filter`): Messages that contain
+        new_chat_photo: Messages that contain
             :attr:`telegram.Message.new_chat_photo`.
-        new_chat_title (:obj:`Filter`): Messages that contain
+        new_chat_title: Messages that contain
             :attr:`telegram.Message.new_chat_title`.
-        pinned_message (:obj:`Filter`): Messages that contain
+        pinned_message: Messages that contain
             :attr:`telegram.Message.pinned_message`.
     """
 
@@ -592,7 +678,7 @@ class Filters(object):
             return bool(message.forward_date)
 
     forwarded = _Forwarded()
-    """:obj:`Filter`: Messages that are forwarded."""
+    """Messages that are forwarded."""
 
     class _Game(BaseFilter):
         name = 'Filters.game'
@@ -601,7 +687,7 @@ class Filters(object):
             return bool(message.game)
 
     game = _Game()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Game`."""
+    """Messages that contain :class:`telegram.Game`."""
 
     class entity(BaseFilter):
         """
@@ -654,7 +740,7 @@ class Filters(object):
             return message.chat.type == Chat.PRIVATE
 
     private = _Private()
-    """:obj:`Filter`: Messages sent in a private chat."""
+    """Messages sent in a private chat."""
 
     class _Group(BaseFilter):
         name = 'Filters.group'
@@ -663,7 +749,7 @@ class Filters(object):
             return message.chat.type in [Chat.GROUP, Chat.SUPERGROUP]
 
     group = _Group()
-    """:obj:`Filter`: Messages sent in a group chat."""
+    """Messages sent in a group chat."""
 
     class user(BaseFilter):
         """Filters messages to allow only those which are from specified user ID.
@@ -749,7 +835,7 @@ class Filters(object):
             return bool(message.invoice)
 
     invoice = _Invoice()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Invoice`."""
+    """Messages that contain :class:`telegram.Invoice`."""
 
     class _SuccessfulPayment(BaseFilter):
         name = 'Filters.successful_payment'
@@ -758,7 +844,7 @@ class Filters(object):
             return bool(message.successful_payment)
 
     successful_payment = _SuccessfulPayment()
-    """:obj:`Filter`: Messages that confirm a :class:`telegram.SuccessfulPayment`."""
+    """Messages that confirm a :class:`telegram.SuccessfulPayment`."""
 
     class _PassportData(BaseFilter):
         name = 'Filters.passport_data'
@@ -767,13 +853,14 @@ class Filters(object):
             return bool(message.passport_data)
 
     passport_data = _PassportData()
-    """:obj:`Filter`: Messages that contain a :class:`telegram.PassportData`"""
+    """Messages that contain a :class:`telegram.PassportData`"""
 
     class language(BaseFilter):
         """Filters messages to only allow those which are from users with a certain language code.
 
-        Note: According to telegrams documentation, every single user does not have the
+        Note:
-        `language_code` attribute.
+            According to official telegram api documentation, not every single user has the
+            `language_code` attribute. Do not count on this filter working on all users.
 
         Examples:
             ``MessageHandler(Filters.language("en"), callback_method)``
@@ -860,13 +947,13 @@ class Filters(object):
         types.
 
     Attributes:
-        message (:obj:`Filter`): Updates with :attr:`telegram.Update.message`
+        message: Updates with :attr:`telegram.Update.message`
-        edited_message (:obj:`Filter`): Updates with :attr:`telegram.Update.edited_message`
+        edited_message: Updates with :attr:`telegram.Update.edited_message`
-        messages (:obj:`Filter`): Updates with either :attr:`telegram.Update.message` or
+        messages: Updates with either :attr:`telegram.Update.message` or
             :attr:`telegram.Update.edited_message`
-        channel_post (:obj:`Filter`): Updates with :attr:`telegram.Update.channel_post`
+        channel_post: Updates with :attr:`telegram.Update.channel_post`
-        edited_channel_post (:obj:`Filter`): Updates with
+        edited_channel_post: Updates with
             :attr:`telegram.Update.edited_channel_post`
-        channel_posts (:obj:`Filter`): Updates with either :attr:`telegram.Update.channel_post` or
+        channel_posts: Updates with either :attr:`telegram.Update.channel_post` or
             :attr:`telegram.Update.edited_channel_post`
     """

telegram/inline/inlinekeyboardbutton.py

@@ -32,7 +32,7 @@ class InlineKeyboardButton(TelegramObject):
         text (:obj:`str`): Label text on the button.
         url (:obj:`str`): Optional. HTTP url to be opened when button is pressed.
         callback_data (:obj:`str`): Optional. Data to be sent in a callback query to the bot when
-            button is pressed, 1-64 bytes.
+            button is pressed, UTF-8 1-64 bytes.
         switch_inline_query (:obj:`str`): Optional. Will prompt the user to select one of their
             chats, open that chat and insert the bot's username and the specified inline query in
             the input field.
@@ -46,7 +46,7 @@ class InlineKeyboardButton(TelegramObject):
         text (:obj:`str`): Label text on the button.
         url (:obj:`str`): HTTP url to be opened when button is pressed.
         callback_data (:obj:`str`, optional): Data to be sent in a callback query to the bot when
-            button is pressed, 1-64 bytes.
+            button is pressed, 1-64 UTF-8 bytes.
         switch_inline_query (:obj:`str`, optional): If set, pressing the button will prompt the
             user to select one of their chats, open that chat and insert the bot's username and the
             specified inline query in the input field. Can be empty, in which case just the bot's