Clear-up documentation by separating reference from examples

readthedocs/extra/basic/entities.rst

@@ -10,6 +10,14 @@ 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``.
 
+.. note::
+
+    When something "entity-like" is required, it means that you need to
+    provide something that can be turned into an entity. These things include,
+    but are not limited to, usernames, exact titles, IDs, ``Peer`` objects,
+    or even entire ``User``, ``Chat`` and ``Channel`` objects and even phone
+    numbers from people you have in your contacts.
+
 Getting entities
 ****************
 

readthedocs/extra/basic/telegram-client.rst

@@ -8,6 +8,11 @@ TelegramClient
 Introduction
 ************
 
+.. note::
+
+    Check the :ref:`telethon-package` if you're looking for the methods
+    reference instead of this tutorial.
+
 The ``TelegramClient`` is the central class of the library, the one
 you will be using most of the time. For this reason, it's important
 to know what it offers.
@@ -86,13 +91,7 @@ Please refer to :ref:`accessing-the-full-api` if these aren't enough,
 and don't be afraid to read the source code of the InteractiveTelegramClient_
 or even the TelegramClient_ itself to learn how it works.
 
+To see the methods available in the client, see :ref:`telethon-package`.
 
 .. _InteractiveTelegramClient: https://github.com/LonamiWebs/Telethon/blob/master/telethon_examples/interactive_telegram_client.py
 .. _TelegramClient: https://github.com/LonamiWebs/Telethon/blob/master/telethon/telegram_client.py
-
-
-
-.. automodule:: telethon.telegram_client
-    :members:
-    :undoc-members:
-    :show-inheritance:

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

@@ -7,7 +7,9 @@ Working with Updates
 
 The library comes with the :mod:`events` module. *Events* are an abstraction
 over what Telegram calls `updates`__, and are meant to ease simple and common
-usage when dealing with them, since there are many updates. Let's dive in!
+usage when dealing with them, since there are many updates. If you're looking
+for the method reference, check :ref:`telethon-events-package`, otherwise,
+let's dive in!
 
 
 .. note::
@@ -114,12 +116,15 @@ for example:
         import random
 
 
-        @client.on(events.NewMessage(chats='TelethonOffTopic', incoming=True))
+        # Either a single item or a list of them will work for the chats.
+        # You can also use the IDs, Peers, or even User/Chat/Channel objects.
+        @client.on(events.NewMessage(chats=('TelethonChat', 'TelethonOffTopic')))
         def normal_handler(event):
             if 'roll' in event.raw_text:
                 event.reply(str(random.randint(1, 6)))
 
 
+        # Similarly, you can use incoming=True for messages that you receive
         @client.on(events.NewMessage(chats='TelethonOffTopic', outgoing=True))
         def admin_handler(event):
             if event.raw_text.startswith('eval'):
@@ -162,14 +167,8 @@ propagation of the update through your handlers to stop:
             pass
 
 
-Events module
-*************
-
-.. automodule:: telethon.events
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
+Remember to check :ref:`telethon-events-package` if you're looking for
+the methods reference.
 
 
 __ https://lonamiwebs.github.io/Telethon/types/update.html

readthedocs/index.rst

@@ -15,7 +15,8 @@ or use the menu on the left. Remember to read the :ref:`changelog`
 when you upgrade!
 
 .. important::
-   If you're new here, you want to read :ref:`getting-started`.
+   If you're new here, you want to read :ref:`getting-started`. If you're
+   looking for the method reference, you should check :ref:`telethon-package`.
 
 
 What is this?

readthedocs/telethon.crypto.rst

@@ -42,14 +42,6 @@ telethon\.crypto\.factorization module
     :undoc-members:
     :show-inheritance:
 
-telethon\.crypto\.libssl module
--------------------------------
-
-.. automodule:: telethon.crypto.libssl
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 telethon\.crypto\.rsa module
 ----------------------------
 

readthedocs/telethon.events.rst

@@ -1,4 +1,9 @@
+.. _telethon-events-package:
+
 telethon\.events package
 ========================
 
-
+.. automodule:: telethon.events
+    :members:
+    :undoc-members:
+    :show-inheritance:

readthedocs/telethon.rst

@@ -1,11 +1,14 @@
+.. _telethon-package:
+
+
 telethon package
 ================
 
 
-telethon\.helpers module
-------------------------
+telethon\.telegram\_client module
+---------------------------------
 
-.. automodule:: telethon.helpers
+.. automodule:: telethon.telegram_client
     :members:
     :undoc-members:
     :show-inheritance:
@@ -18,10 +21,18 @@ telethon\.telegram\_bare\_client module
     :undoc-members:
     :show-inheritance:
 
-telethon\.telegram\_client module
----------------------------------
+telethon\.utils module
+----------------------
 
-.. automodule:: telethon.telegram_client
+.. automodule:: telethon.utils
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.helpers module
+------------------------
+
+.. automodule:: telethon.helpers
     :members:
     :undoc-members:
     :show-inheritance:
@@ -42,18 +53,10 @@ telethon\.update\_state module
     :undoc-members:
     :show-inheritance:
 
-telethon\.utils module
-----------------------
+telethon\.sessions module
+-------------------------
 
-.. automodule:: telethon.utils
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-telethon\.session module
-------------------------
-
-.. automodule:: telethon.session
+.. automodule:: telethon.sessions
     :members:
     :undoc-members:
     :show-inheritance: