Several documentation enhancements and build warnings fixes

- Made the documentation even more friendly towards newbies.
- Eased the usage of methods like get history which now set
  a default empty message for message actions and vice versa.
- Fixed some docstring documentations too.
- Updated the old normal docs/ to link back and forth RTD.
- Fixed the version of the documentation, now auto-loaded.

readthedocs/extra/advanced-usage/accessing-the-full-api.rst

@@ -14,8 +14,10 @@ through a sorted list of everything you can do.
 
 .. note::
 
-    Removing the hand crafted documentation for methods is still
-    a work in progress!
+    The reason to keep both https://lonamiwebs.github.io/Telethon and this
+    documentation alive is that the former allows instant search results
+    as you type, and a "Copy import" button. If you like namespaces, you
+    can also do ``from telethon.tl import types, functions``. Both work.
 
 
 You should also refer to the documentation to see what the objects
@@ -39,8 +41,8 @@ If you're going to use a lot of these, you may do:
 
     .. code-block:: python
     
-        import telethon.tl.functions as tl
-        # We now have access to 'tl.messages.SendMessageRequest'
+        from telethon.tl import types, functions
+        # We now have access to 'functions.messages.SendMessageRequest'
 
 We see that this request must take at least two parameters, a ``peer``
 of type `InputPeer`__, and a ``message`` which is just a Python
@@ -82,6 +84,14 @@ every time its used, simply call ``.get_input_peer``:
         from telethon import utils
         peer = utils.get_input_user(entity)
 
+
+.. note::
+
+    Since ``v0.16.2`` this is further simplified. The ``Request`` itself
+    will call ``client.get_input_entity()`` for you when required, but
+    it's good to remember what's happening.
+
+
 After this small parenthesis about ``.get_entity`` versus
 ``.get_input_entity``, we have everything we need. To ``.invoke()`` our
 request we do:

readthedocs/extra/basic/creating-a-client.rst

@@ -93,6 +93,8 @@ method also accepts a ``phone=`` and ``bot_token`` parameters.
 You can use either, as both will work. Determining which
 is just a matter of taste, and how much control you need.
 
+Remember that you can get yourself at any time with ``client.get_me()``.
+
 
 .. note::
     If you want to use a **proxy**, you have to `install PySocks`__

readthedocs/extra/basic/entities.rst

@@ -10,21 +10,6 @@ The library widely uses the concept of "entities". An entity will refer
 to any ``User``, ``Chat`` or ``Channel`` object that the API may return
 in response to certain methods, such as ``GetUsersRequest``.
 
-To save bandwidth, the API also makes use of their "input" versions.
-The input version of an entity (e.g. ``InputPeerUser``, ``InputChat``,
-etc.) only contains the minimum required information that's required
-for Telegram to be able to identify who you're referring to: their ID
-and hash. This ID/hash pair is unique per user, so if you use the pair
-given by another user **or bot** it will **not** work.
-
-To save *even more* bandwidth, the API also makes use of the ``Peer``
-versions, which just have an ID. This serves to identify them, but
-peers alone are not enough to use them. You need to know their hash
-before you can "use them".
-
-Luckily, the library tries to simplify this mess the best it can.
-
-
 Getting entities
 ****************
 
@@ -58,8 +43,8 @@ you're able to just do this:
         my_channel = client.get_entity(PeerChannel(some_id))
 
 
-All methods in the :ref:`telegram-client` call ``.get_entity()`` to further
-save you from the hassle of doing so manually, so doing things like
+All methods in the :ref:`telegram-client` call ``.get_input_entity()`` to
+further save you from the hassle of doing so manually, so doing things like
 ``client.send_message('lonami', 'hi!')`` is possible.
 
 Every entity the library "sees" (in any response to any call) will by
@@ -72,7 +57,27 @@ made to obtain the required information.
 Entities vs. Input Entities
 ***************************
 
-As we mentioned before, API calls don't need to know the whole information
+.. note::
+
+    Don't worry if you don't understand this section, just remember some
+    of the details listed here are important. When you're calling a method,
+    don't call ``.get_entity()`` before, just use the username or phone,
+    or the entity retrieved by other means like ``.get_dialogs()``.
+
+
+To save bandwidth, the API also makes use of their "input" versions.
+The input version of an entity (e.g. ``InputPeerUser``, ``InputChat``,
+etc.) only contains the minimum required information that's required
+for Telegram to be able to identify who you're referring to: their ID
+and hash. This ID/hash pair is unique per user, so if you use the pair
+given by another user **or bot** it will **not** work.
+
+To save *even more* bandwidth, the API also makes use of the ``Peer``
+versions, which just have an ID. This serves to identify them, but
+peers alone are not enough to use them. You need to know their hash
+before you can "use them".
+
+As we just mentioned, API calls don't need to know the whole information
 about the entities, only their ID and hash. For this reason, another method,
 ``.get_input_entity()`` is available. This will always use the cache while
 possible, making zero API calls most of the time. When a request is made,
@@ -85,3 +90,15 @@ the most recent information about said entity, but invoking requests don't
 need this information, just the ``InputPeer``. Only use ``.get_entity()``
 if you need to get actual information, like the username, name, title, etc.
 of the entity.
+
+To further simplify the workflow, since the version ``0.16.2`` of the
+library, the raw requests you make to the API are also able to call
+``.get_input_entity`` wherever needed, so you can even do things like:
+
+    .. code-block:: python
+
+        client(SendMessageRequest('username', 'hello'))
+
+The library will call the ``.resolve()`` method of the request, which will
+resolve ``'username'`` with the appropriated ``InputPeer``. Don't worry if
+you don't get this yet, but remember some of the details here are important.

readthedocs/extra/basic/getting-started.rst

@@ -1,7 +1,5 @@
-.. Telethon documentation master file, created by
-   sphinx-quickstart on Fri Nov 17 15:36:11 2017.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. _getting-started:
+
 
 ===============
 Getting Started
@@ -39,13 +37,36 @@ Basic Usage
 
    .. code-block:: python
 
-       print(me.stringify())
+       # Getting information about yourself
+       print(client.get_me().stringify())
 
-       client.send_message('username', 'Hello! Talking to you from Telethon')
+       # Sending a message (you can use 'me' or 'self' to message yourself)
+       client.send_message('username', 'Hello World from Telethon!')
+
+       # Sending a file
        client.send_file('username', '/home/myself/Pictures/holidays.jpg')
 
-       client.download_profile_photo(me)
+       # Retrieving messages from a chat
+       from telethon import utils
+       for message in client.get_message_history('username', limit=10):
+           print(utils.get_display_name(message.sender), message.message)
+
+       # Listing all the dialogs (conversations you have open)
+       for dialog in client.get_dialogs(limit=10):
+           print(utils.get_display_name(dialog.entity), dialog.draft.message)
+
+       # Downloading profile photos (default path is the working directory)
+       client.download_profile_photo('username')
+
+       # Once you have a message with .media (if message.media)
+       # you can download it using client.download_media():
        messages = client.get_message_history('username')
        client.download_media(messages[0])
 
    **More details**: :ref:`telegram-client`
+
+
+----------
+
+You can continue by clicking on the "More details" link below each
+snippet of code or the "Next" button at the bottom of the page.

readthedocs/extra/basic/installation.rst

@@ -29,7 +29,9 @@ You can also install the library directly from GitHub or a fork:
         $ cd Telethon/
         # pip install -Ue .
 
-If you don't have root access, simply pass the ``--user`` flag to the pip command.
+If you don't have root access, simply pass the ``--user`` flag to the pip
+command. If you want to install a specific branch, append ``@branch`` to
+the end of the first install command.
 
 
 Manual Installation
@@ -49,7 +51,8 @@ Manual Installation
 
 5. Done!
 
-To generate the documentation, ``cd docs`` and then ``python3 generate.py``.
+To generate the `method documentation`__, ``cd docs`` and then
+``python3 generate.py`` (if some pages render bad do it twice).
 
 
 Optional dependencies
@@ -62,5 +65,6 @@ will also work without it.
 
 __ https://github.com/ricmoo/pyaes
 __ https://pypi.python.org/pypi/pyaes
-__ https://github.com/sybrenstuvel/python-rsa/
+__ https://github.com/sybrenstuvel/python-rsa
 __ https://pypi.python.org/pypi/rsa/3.4.2
+__ https://lonamiwebs.github.io/Telethon

readthedocs/extra/basic/telegram-client.rst

@@ -43,30 +43,29 @@ how the library refers to either of these:
         lonami = client.get_entity('lonami')
 
 The so called "entities" are another important whole concept on its own,
-and you should
-Note that saving and using these entities will be more important when
-Accessing the Full API. For now, this is a good way to get information
-about an user or chat.
+but for now you don't need to worry about it. Simply know that they are
+a good way to get information about an user, chat or channel.
 
-Other common methods for quick scripts are also available:
+Many other common methods for quick scripts are also available:
 
     .. code-block:: python
 
-        # Sending a message (use an entity/username/etc)
-        client.send_message('TheAyyBot', 'ayy')
+        # Note that you can use 'me' or 'self' to message yourself
+        client.send_message('username', 'Hello World from Telethon!')
 
-        # Sending a photo, or a file
-        client.send_file(myself, '/path/to/the/file.jpg', force_document=True)
+        client.send_file('username', '/home/myself/Pictures/holidays.jpg')
 
-        # Downloading someone's profile photo. File is saved to 'where'
-        where = client.download_profile_photo(someone)
+        # The utils package has some goodies, like .get_display_name()
+        from telethon import utils
+        for message in client.get_message_history('username', limit=10):
+            print(utils.get_display_name(message.sender), message.message)
 
-        # Retrieving the message history
-        messages = client.get_message_history(someone)
+        # Dialogs are the conversations you have open
+        for dialog in client.get_dialogs(limit=10):
+            print(utils.get_display_name(dialog.entity), dialog.draft.message)
 
-        # Downloading the media from a specific message
-        # You can specify either a directory, a filename, or nothing at all
-        where = client.download_media(message, '/path/to/output')
+        # Default path is the working directory
+        client.download_profile_photo('username')
 
         # Call .disconnect() when you're done
         client.disconnect()

readthedocs/extra/basic/working-with-updates.rst

@@ -4,6 +4,12 @@
 Working with Updates
 ====================
 
+
+.. note::
+
+    There are plans to make working with updates more friendly. Stay tuned!
+
+
 .. contents::
 
 

readthedocs/extra/examples/bots.rst

@@ -3,6 +3,11 @@ Bots
 ====
 
 
+.. note::
+
+    These examples assume you have read :ref:`accessing-the-full-api`.
+
+
 Talking to Inline Bots
 **********************
 

readthedocs/extra/examples/chats-and-channels.rst

@@ -3,6 +3,11 @@ Working with Chats and Channels
 ===============================
 
 
+.. note::
+
+    These examples assume you have read :ref:`accessing-the-full-api`.
+
+
 Joining a chat or channel
 *************************
 

readthedocs/extra/examples/working-with-messages.rst

@@ -3,6 +3,11 @@ Working with messages
 =====================
 
 
+.. note::
+
+    These examples assume you have read :ref:`accessing-the-full-api`.
+
+
 Forwarding messages
 *******************